stefan.tollkuehn/atocal
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
stefan.tollkuehn committed 2026-10-07 21:57:34 +02:00
commit 7aac2718b5
7 files changed
+727
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+41
View File
@@ -0,0 +1,41 @@
# AGENT.MD
- When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more.
- Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.
- Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. Keep self-explanatory, one-off values inline to avoid clutter. If a value comes from a spec (e.g. HTTP 200 OK), use a constant regardless.
- Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.
- Keep function names short. Less than 30 characters.
- Use enums instead of booleans for function parameters.
- Let the reader of the code breathe. Add empty lines between logical blocks of code.
- Add a small, to the point, comment to explain *what* the block does and *why*. Use examples when possible. Propose ASCII drawings to explain complete systems.
- Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.
- Program to levels of abstraction. Lower-level mechanics (e.g., raw hardware I/O, sector parsing, direct socket streams) must be encapsulated in a dedicated driver/abstraction layer. Expose clean, high-level APIs to the rest of the application so calling code works with domain concepts, not raw implementation details.
- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature.
- Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer).
- Always use {}, even on a one-line "if" statement.
When you write a commit message, follow these 7 rules:
Rule 1: Separate the subject line from the body with a single blank line.
Rule 2: Limit the subject line to 50 characters (72 is the absolute hard limit).
Rule 3: Capitalize the first letter of the subject line.
Rule 4: Do not end the subject line with a period.
Rule 5: Use the imperative mood in the subject line (e.g., "Fix bug," "Add feature,"
not "Fixed" or "Adds"). Test formula: It must complete the sentence: "If applied,
this commit will [your subject line here]".
Rule 6: Wrap the body text manually at 72 characters to prevent Git formatting issues.
Rule 7: Use the body to explain what and why vs. how. Assume the code explains the how;
the message must explain the context and reasoning.
- If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.
appinfo/info.xml
+18
View File
@@ -0,0 +1,18 @@
<?xml version="1.0"?>
<info xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://apps.nextcloud.com/schema/apps/info.xsd">
<id>jitsi_calendar</id>
<name>Jitsi Calendar</name>
<summary>Create Jitsi meetings in the user's Nextcloud Calendar</summary>
<description>
Allows the Jitsi meeting launcher to create calendar events in the authenticated user's Nextcloud Calendar.
</description>
<version>1.0.0</version>
<licence>AGPL</licence>
<author>Stefan Tollkühn s.tollkuehn@bnvb-ingenieure.de</author>
<namespace>JitsiCalendar</namespace>
<category>integration</category>
<dependencies>
<nextcloud min-version="34" max-version="34"/>
</dependencies>
<screenshot></screenshot>
</info>
appinfo/routes.php
+18
View File
@@ -0,0 +1,18 @@
<?php
declare(strict_types=1);
return [
'routes' => [
[
'name' => 'calendar#confirm',
'url' => '/confirm',
'verb' => 'GET',
],
[
'name' => 'calendar#create',
'url' => '/create',
'verb' => 'POST',
],
],
];
lib/AppInfo/Application.php
+34
View File
@@ -0,0 +1,34 @@
<?php
declare(strict_types=1);
namespace OCA\JitsiCalendar\AppInfo;
use OCA\JitsiCalendar\Controller\CalendarController;
use OCP\AppFramework\App;
use OCP\AppFramework\IAppContainer;
class Application extends App
{
public const APP_ID = 'jitsi_calendar';
public function __construct(array $urlParams = [])
{
parent::__construct(self::APP_ID, $urlParams);
$container = $this->getContainer();
$container->registerService(
CalendarController::class,
function (IAppContainer $c): CalendarController {
return new CalendarController(
self::APP_ID,
$c->get('Request'),
$c->get(\OCP\Calendar\IManager::class),
$c->get(\OCP\IUserSession::class),
$c->get(\OCP\IURLGenerator::class)
);
}
);
}
}
lib/Controller/CalendarController.php
+394
View File
@@ -0,0 +1,394 @@
<?php
declare(strict_types=1);
namespace OCA\JitsiCalendar\Controller;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\RedirectResponse;
use OCP\AppFramework\Http\TemplateResponse;
use OCP\Calendar\IManager;
use OCP\IRequest;
use OCP\IUserSession;
use OCP\IURLGenerator;
use OCP\Util;
use OCP\IConfig;
class CalendarController extends Controller
{
private IManager $calendarManager;
private IUserSession $userSession;
private IURLGenerator $urlGenerator;
private IConfig $config;
public function __construct(
string $appName,
IRequest $request,
IManager $calendarManager,
IUserSession $userSession,
IURLGenerator $urlGenerator
) {
parent::__construct($appName, $request);
$this->calendarManager = $calendarManager;
$this->userSession = $userSession;
$this->urlGenerator = $urlGenerator;
}
/**
* Show event confirmation.
*
* The route itself requires an authenticated Nextcloud user.
* If the user is not authenticated, Nextcloud's normal
* authentication flow takes over before the controller executes.
*/
public function confirm(
string $summary = '',
string $description = '',
string $start = '',
string $end = '',
string $organizer = '',
string $location = '',
string $url = ''
): TemplateResponse {
$data = $this->validateEventData(
$summary,
$description,
$start,
$end,
$organizer,
$location,
$url
);
return new TemplateResponse(
self::APP_ID,
'confirm',
[
'summary' => $data['summary'],
'description' => $data['description'],
'start' => $data['start'],
'end' => $data['end'],
'organizer' => $data['organizer'],
'location' => $data['location'],
'url' => $data['url'],
'createUrl' => $this->urlGenerator->linkToRoute(
self::APP_ID . '.calendar.create'
),
]
);
}
/**
* Create the calendar event.
*/
public function create(
string $summary = '',
string $description = '',
string $start = '',
string $end = '',
string $organizer = '',
string $location = '',
string $url = ''
): RedirectResponse {
$data = $this->validateEventData(
$summary,
$description,
$start,
$end,
$organizer,
$location,
$url
);
$user = $this->userSession->getUser();
if ($user === null) {
throw new \RuntimeException('No authenticated Nextcloud user.');
}
$calendars = $this->calendarManager->getCalendarsForUser(
$user->getUID()
);
$writableCalendar = null;
foreach ($calendars as $calendar) {
/*
* getCalendarsForUser() returns ICalendar objects.
* Only calendars implementing ICreateFromString are writable.
*/
if ($calendar instanceof \OCP\Calendar\ICreateFromString) {
$writableCalendar = $calendar;
break;
}
}
if ($writableCalendar === null) {
throw new \RuntimeException(
'No writable calendar is available for this user.'
);
}
$uid = 'jitsi-' . bin2hex(random_bytes(16))
. '@meet.bnvb.eu';
$ics = $this->buildIcs(
$uid,
$data['summary'],
$data['description'],
$data['start'],
$data['end'],
$data['organizer'],
$data['location'],
$data['url']
);
$filename = $uid . '.ics';
$writableCalendar->createFromString(
$filename,
$ics
);
/*
* Open the Nextcloud Calendar application.
*/
$calendarUrl = $this->urlGenerator->linkToRoute(
'calendar.view.index'
);
return new RedirectResponse($calendarUrl);
}
/**
* Validate and normalize all event input.
*/
private function validateEventData(
string $summary,
string $description,
string $start,
string $end,
string $organizer,
string $location,
string $url
): array {
$summary = trim($summary);
$description = trim($description);
$start = trim($start);
$end = trim($end);
$organizer = trim($organizer);
$location = trim($location);
$url = trim($url);
if ($summary === '') {
throw new \InvalidArgumentException(
'Meeting title is required.'
);
}
if (mb_strlen($summary) > 255) {
throw new \InvalidArgumentException(
'Meeting title is too long.'
);
}
if ($description !== '' && mb_strlen($description) > 10000) {
throw new \InvalidArgumentException(
'Meeting description is too long.'
);
}
$startDate = $this->parseLocalDateTime($start);
$endDate = $this->parseLocalDateTime($end);
if ($endDate <= $startDate) {
throw new \InvalidArgumentException(
'End time must be after start time.'
);
}
if ($location !== '') {
$locationParts = parse_url($location);
if (
$locationParts === false ||
!isset($locationParts['scheme']) ||
!in_array(
strtolower($locationParts['scheme']),
['https'],
true
)
) {
throw new \InvalidArgumentException(
'Location must be an HTTPS URL.'
);
}
}
if ($url !== '') {
$urlParts = parse_url($url);
if (
$urlParts === false ||
!isset($urlParts['scheme']) ||
!in_array(
strtolower($urlParts['scheme']),
['https'],
true
)
) {
throw new \InvalidArgumentException(
'Meeting URL must be an HTTPS URL.'
);
}
}
if ($organizer !== '' && !filter_var(
$organizer,
FILTER_VALIDATE_EMAIL
)) {
throw new \InvalidArgumentException(
'Invalid organizer email address.'
);
}
return [
'summary' => $summary,
'description' => $description,
'start' => $startDate,
'end' => $endDate,
'organizer' => $organizer,
'location' => $location,
'url' => $url,
];
}
/**
* Parse datetime-local values.
*
* datetime-local has no timezone information, so we intentionally
* interpret the value in the Nextcloud server's configured timezone.
*/
private function parseLocalDateTime(string $value): \DateTimeImmutable
{
$date = \DateTimeImmutable::createFromFormat(
'Y-m-d\TH:i',
$value
);
if ($date === false) {
$date = \DateTimeImmutable::createFromFormat(
'Y-m-d\TH:i:s',
$value
);
}
if ($date === false) {
throw new \InvalidArgumentException(
'Invalid date/time.'
);
}
return $date;
}
/**
* Build an RFC 5545 iCalendar event.
*/
private function buildIcs(
string $uid,
string $summary,
string $description,
\DateTimeImmutable $start,
\DateTimeImmutable $end,
string $organizer,
string $location,
string $url
): string {
$now = new \DateTimeImmutable('now');
$dtStamp = $now->setTimezone(
new \DateTimeZone('UTC')
)->format('Ymd\THis\Z');
$dtStart = $start->format('Ymd\THis');
$dtEnd = $end->format('Ymd\THis');
$lines = [
'BEGIN:VCALENDAR',
'VERSION:2.0',
'PRODID:-//BNVB//Jitsi Calendar//EN',
'CALSCALE:GREGORIAN',
'METHOD:PUBLISH',
'BEGIN:VEVENT',
'UID:' . $this->escapeIcsText($uid),
'DTSTAMP:' . $dtStamp,
'DTSTART:' . $dtStart,
'DTEND:' . $dtEnd,
'SUMMARY:' . $this->escapeIcsText($summary),
];
if ($description !== '') {
$lines[] =
'DESCRIPTION:' .
$this->escapeIcsText($description);
}
if ($location !== '') {
$lines[] =
'LOCATION:' .
$this->escapeIcsText($location);
}
if ($organizer !== '') {
$lines[] =
'ORGANIZER:MAILTO:' .
$this->escapeIcsText($organizer);
}
if ($url !== '') {
$lines[] =
'URL:' .
$this->escapeIcsText($url);
}
$lines[] = 'STATUS:CONFIRMED';
$lines[] = 'SEQUENCE:0';
$lines[] = 'TRANSP:OPAQUE';
$lines[] = 'BEGIN:VALARM';
$lines[] = 'ACTION:DISPLAY';
$lines[] = 'DESCRIPTION:Reminder';
$lines[] = 'TRIGGER:-PT15M';
$lines[] = 'END:VALARM';
$lines[] = 'END:VEVENT';
$lines[] = 'END:VCALENDAR';
return implode("\r\n", $lines) . "\r\n";
}
private function escapeIcsText(string $value): string
{
return str_replace(
[
'\\',
';',
',',
"\r\n",
"\r",
"\n",
],
[
'\\\\',
'\;',
'\,',
'\n',
'\n',
'\n',
],
$value
);
}
}
templates/confirm.php
+147
View File
@@ -0,0 +1,147 @@
<?php
declare(strict_types=1);
$h = static function (string $value): string {
return htmlspecialchars(
$value,
ENT_QUOTES | ENT_SUBSTITUTE,
'UTF-8'
);
};
?>
<div id="app-content">
<div class="jitsi-calendar-container">
<div class="jitsi-calendar-card">
<h1>
Add Jitsi Meeting to Calendar
</h1>
<p class="jitsi-calendar-intro">
The following meeting will be added to your
Nextcloud Calendar.
</p>
<div class="jitsi-calendar-details">
<div class="jitsi-calendar-row">
<strong>Title</strong>
<span><?= $h($_['summary']) ?></span>
</div>
<?php if ($_['description'] !== ''): ?>
<div class="jitsi-calendar-row">
<strong>Description</strong>
<span class="description">
<?= nl2br($h($_['description'])) ?>
</span>
</div>
<?php endif; ?>
<div class="jitsi-calendar-row">
<strong>Start</strong>
<span><?= $h($_['start']) ?></span>
</div>
<div class="jitsi-calendar-row">
<strong>End</strong>
<span><?= $h($_['end']) ?></span>
</div>
<?php if ($_['organizer'] !== ''): ?>
<div class="jitsi-calendar-row">
<strong>Organizer</strong>
<span><?= $h($_['organizer']) ?></span>
</div>
<?php endif; ?>
<?php if ($_['location'] !== ''): ?>
<div class="jitsi-calendar-row">
<strong>Location</strong>
<span>
<a
href="<?= $h($_['location']) ?>"
target="_blank"
rel="noopener noreferrer"
>
<?= $h($_['location']) ?>
</a>
</span>
</div>
<?php endif; ?>
</div>
<form
method="post"
action="<?= $h($_['createUrl']) ?>"
>
<input
type="hidden"
name="summary"
value="<?= $h($_['summary']) ?>"
>
<input
type="hidden"
name="description"
value="<?= $h($_['description']) ?>"
>
<input
type="hidden"
name="start"
value="<?= $h($_['start']) ?>"
>
<input
type="hidden"
name="end"
value="<?= $h($_['end']) ?>"
>
<input
type="hidden"
name="organizer"
value="<?= $h($_['organizer']) ?>"
>
<input
type="hidden"
name="location"
value="<?= $h($_['location']) ?>"
>
<input
type="hidden"
name="url"
value="<?= $h($_['url']) ?>"
>
<div class="jitsi-calendar-actions">
<button
type="submit"
class="primary"
>
Add to Nextcloud Calendar
</button>
<a
href="https://cloud.bnvb-ingenieure.de/"
class="secondary"
>
Cancel
</a>
</div>
</form>
</div>
</div>
</div>
templates/style.css
+75
View File
@@ -0,0 +1,75 @@
.jitsi-calendar-container {
max-width: 760px;
margin: 60px auto;
padding: 20px;
}
.jitsi-calendar-card {
background: var(--color-main-background);
border: 1px solid var(--color-border);
border-radius: 12px;
padding: 32px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
}
.jitsi-calendar-card h1 {
margin-top: 0;
margin-bottom: 12px;
}
.jitsi-calendar-intro {
color: var(--color-text-maxcontrast);
margin-bottom: 28px;
}
.jitsi-calendar-details {
border-top: 1px solid var(--color-border);
border-bottom: 1px solid var(--color-border);
margin-bottom: 28px;
}
.jitsi-calendar-row {
display: grid;
grid-template-columns: 150px 1fr;
gap: 16px;
padding: 14px 0;
border-bottom: 1px solid var(--color-border);
}
.jitsi-calendar-row:last-child {
border-bottom: 0;
}
.jitsi-calendar-row span {
overflow-wrap: anywhere;
}
.jitsi-calendar-row .description {
white-space: normal;
}
.jitsi-calendar-actions {
display: flex;
gap: 12px;
flex-wrap: wrap;
}
.jitsi-calendar-actions button,
.jitsi-calendar-actions a {
display: inline-block;
padding: 10px 18px;
border-radius: 6px;
text-decoration: none;
cursor: pointer;
}
.jitsi-calendar-actions button.primary {
background: var(--color-primary-element);
color: var(--color-primary-element-text);
border: 0;
}
.jitsi-calendar-actions a.secondary {
border: 1px solid var(--color-border);
color: var(--color-main-text);
}