@portel/photon-core 2.10.1 → 2.12.0

package/dist/schedule.js

@@ -0,0 +1,283 @@
+/**
+ * Runtime Scheduling System
+ *
+ * Programmatic scheduling for photons — create, pause, resume, and cancel
+ * scheduled tasks at runtime. Available as `this.schedule` on Photon.
+ *
+ * Complements static `@scheduled`/`@cron` JSDoc tags with dynamic scheduling.
+ * Schedules persist to disk; the daemon reads and executes them.
+ *
+ * Storage: ~/.photon/schedules/{photonId}/{taskId}.json
+ *
+ * @example
+ * ```typescript
+ * export default class Cleanup extends Photon {
+ *   async setup() {
+ *     await this.schedule.create({
+ *       name: 'nightly-cleanup',
+ *       schedule: '0 0 * * *',
+ *       method: 'purge',
+ *       params: { olderThan: 30 },
+ *     });
+ *   }
+ *
+ *   async purge({ olderThan }: { olderThan: number }) {
+ *     // ... cleanup logic
+ *   }
+ * }
+ * ```
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { randomUUID } from 'crypto';
+// ── Cron Shorthands ────────────────────────────────────────────────────
+const CRON_SHORTHANDS = {
+    '@yearly': '0 0 1 1 *',
+    '@annually': '0 0 1 1 *',
+    '@monthly': '0 0 1 * *',
+    '@weekly': '0 0 * * 0',
+    '@daily': '0 0 * * *',
+    '@midnight': '0 0 * * *',
+    '@hourly': '0 * * * *',
+};
+/**
+ * Resolve cron shorthands and validate basic format.
+ * Returns the resolved 5-field cron expression.
+ */
+function resolveCron(schedule) {
+    const trimmed = schedule.trim();
+    // Check shorthands
+    const shorthand = CRON_SHORTHANDS[trimmed.toLowerCase()];
+    if (shorthand)
+        return shorthand;
+    // Validate 5-field cron format
+    const fields = trimmed.split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`Invalid cron expression: '${schedule}'. Expected 5 fields (minute hour day month weekday) or a shorthand (@hourly, @daily, @weekly, @monthly, @yearly).`);
+    }
+    return trimmed;
+}
+// ── Storage Helpers ────────────────────────────────────────────────────
+function getSchedulesDir() {
+    return process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules');
+}
+function photonScheduleDir(photonId) {
+    const safeName = photonId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return path.join(getSchedulesDir(), safeName);
+}
+function taskPath(photonId, taskId) {
+    return path.join(photonScheduleDir(photonId), `${taskId}.json`);
+}
+async function ensureDir(dir) {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+}
+// ── Schedule Provider ──────────────────────────────────────────────────
+/**
+ * Runtime Schedule Provider
+ *
+ * Provides CRUD operations for scheduled tasks.
+ * Tasks are persisted as JSON files that the daemon watches and executes.
+ */
+export class ScheduleProvider {
+    _photonId;
+    constructor(photonId) {
+        this._photonId = photonId;
+    }
+    /**
+     * Create a new scheduled task
+     *
+     * @example
+     * ```typescript
+     * await this.schedule.create({
+     *   name: 'daily-report',
+     *   schedule: '0 9 * * *',
+     *   method: 'generate',
+     *   params: { format: 'pdf' },
+     * });
+     * ```
+     */
+    async create(options) {
+        const cron = resolveCron(options.schedule);
+        // Check for duplicate name
+        const existing = await this.getByName(options.name);
+        if (existing) {
+            throw new Error(`Schedule '${options.name}' already exists (id: ${existing.id}). Use update() to modify it.`);
+        }
+        const task = {
+            id: randomUUID(),
+            name: options.name,
+            description: options.description,
+            cron,
+            method: options.method,
+            params: options.params || {},
+            fireOnce: options.fireOnce ?? false,
+            maxExecutions: options.maxExecutions ?? 0,
+            status: 'active',
+            createdAt: new Date().toISOString(),
+            executionCount: 0,
+            photonId: this._photonId,
+        };
+        await this._save(task);
+        return task;
+    }
+    /**
+     * Get a scheduled task by ID
+     */
+    async get(taskId) {
+        try {
+            const content = await fs.readFile(taskPath(this._photonId, taskId), 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Get a scheduled task by name
+     */
+    async getByName(name) {
+        const tasks = await this.list();
+        return tasks.find(t => t.name === name) || null;
+    }
+    /**
+     * List all scheduled tasks, optionally filtered by status
+     */
+    async list(status) {
+        const dir = photonScheduleDir(this._photonId);
+        let files;
+        try {
+            files = await fs.readdir(dir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const tasks = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const content = await fs.readFile(path.join(dir, file), 'utf-8');
+                const task = JSON.parse(content);
+                if (!status || task.status === status) {
+                    tasks.push(task);
+                }
+            }
+            catch {
+                // Skip corrupt files
+            }
+        }
+        return tasks.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    /**
+     * Update an existing scheduled task
+     */
+    async update(taskId, updates) {
+        const task = await this.get(taskId);
+        if (!task) {
+            throw new Error(`Schedule not found: ${taskId}`);
+        }
+        if (updates.schedule !== undefined) {
+            task.cron = resolveCron(updates.schedule);
+        }
+        if (updates.method !== undefined)
+            task.method = updates.method;
+        if (updates.params !== undefined)
+            task.params = updates.params;
+        if (updates.description !== undefined)
+            task.description = updates.description;
+        if (updates.fireOnce !== undefined)
+            task.fireOnce = updates.fireOnce;
+        if (updates.maxExecutions !== undefined)
+            task.maxExecutions = updates.maxExecutions;
+        await this._save(task);
+        return task;
+    }
+    /**
+     * Pause a scheduled task (stops execution until resumed)
+     */
+    async pause(taskId) {
+        const task = await this.get(taskId);
+        if (!task)
+            throw new Error(`Schedule not found: ${taskId}`);
+        if (task.status !== 'active') {
+            throw new Error(`Cannot pause task with status '${task.status}'. Only active tasks can be paused.`);
+        }
+        task.status = 'paused';
+        await this._save(task);
+        return task;
+    }
+    /**
+     * Resume a paused scheduled task
+     */
+    async resume(taskId) {
+        const task = await this.get(taskId);
+        if (!task)
+            throw new Error(`Schedule not found: ${taskId}`);
+        if (task.status !== 'paused') {
+            throw new Error(`Cannot resume task with status '${task.status}'. Only paused tasks can be resumed.`);
+        }
+        task.status = 'active';
+        await this._save(task);
+        return task;
+    }
+    /**
+     * Cancel (delete) a scheduled task
+     */
+    async cancel(taskId) {
+        try {
+            await fs.unlink(taskPath(this._photonId, taskId));
+            return true;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return false;
+            throw err;
+        }
+    }
+    /**
+     * Cancel a scheduled task by name
+     */
+    async cancelByName(name) {
+        const task = await this.getByName(name);
+        if (!task)
+            return false;
+        return this.cancel(task.id);
+    }
+    /**
+     * Check if a schedule with the given name exists
+     */
+    async has(name) {
+        const task = await this.getByName(name);
+        return task !== null;
+    }
+    /**
+     * Cancel all scheduled tasks for this photon
+     */
+    async cancelAll() {
+        const tasks = await this.list();
+        let count = 0;
+        for (const task of tasks) {
+            if (await this.cancel(task.id))
+                count++;
+        }
+        return count;
+    }
+    /** @internal */
+    async _save(task) {
+        const dir = photonScheduleDir(this._photonId);
+        await ensureDir(dir);
+        await fs.writeFile(taskPath(this._photonId, task.id), JSON.stringify(task, null, 2));
+    }
+}
+//# sourceMappingURL=schedule.js.map

package/dist/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAqEpC,0EAA0E;AAE1E,MAAM,eAAe,GAA2B;IAC9C,SAAS,EAAI,WAAW;IACxB,WAAW,EAAE,WAAW;IACxB,UAAU,EAAG,WAAW;IACxB,SAAS,EAAI,WAAW;IACxB,QAAQ,EAAK,WAAW;IACxB,WAAW,EAAE,WAAW;IACxB,SAAS,EAAI,WAAW;CACzB,CAAC;AAEF;;;GAGG;AACH,SAAS,WAAW,CAAC,QAAgB;IACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEhC,mBAAmB;IACnB,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACzD,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,+BAA+B;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,6BAA6B,QAAQ,oHAAoH,CAC1J,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0EAA0E;AAE1E,SAAS,eAAe;IACtB,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAgB;IACzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,QAAQ,CAAC,QAAgB,EAAE,MAAc;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;AAClE,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC;IACvC,CAAC;AACH,CAAC;AAED,0EAA0E;AAE1E;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,CAAS;IAE1B,YAAY,QAAgB;QAC1B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,CAAC,OAA8B;QACzC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE3C,2BAA2B;QAC3B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACpD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,aAAa,OAAO,CAAC,IAAI,yBAAyB,QAAQ,CAAC,EAAE,+BAA+B,CAAC,CAAC;QAChH,CAAC;QAED,MAAM,IAAI,GAAkB;YAC1B,EAAE,EAAE,UAAU,EAAE;YAChB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,IAAI;YACJ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;YAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;YACnC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,CAAC;YACzC,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,cAAc,EAAE,CAAC;YACjB,QAAQ,EAAE,IAAI,CAAC,SAAS;SACzB,CAAC;QAEF,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,MAAc;QACtB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;YAC7E,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YACvC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,IAAY;QAC1B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,MAAuB;QAChC,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,EAAE,CAAC;YACrC,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,KAAK,GAAoB,EAAE,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,SAAS;YACtC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;gBACjE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAC;gBAClD,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;oBACtC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACnB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,qBAAqB;YACvB,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,OAA8B;QACzD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QAC9E,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACrE,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS;YAAE,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAEpF,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,MAAM,qCAAqC,CAAC,CAAC;QACtG,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc;QACzB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,CAAC,MAAM,sCAAsC,CAAC,CAAC;QACxG,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;QACvB,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;YAClD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;YACxC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxC,OAAO,IAAI,KAAK,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS;QACb,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,KAAK,EAAE,CAAC;QAC1C,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gBAAgB;IACR,KAAK,CAAC,KAAK,CAAC,IAAmB;QACrC,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC9C,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACrB,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;CACF"}

package/dist/schema-extractor.d.ts

@@ -57,6 +57,11 @@ export declare class SchemaExtractor {
      * Extracts: type, optional, readonly
      */
     private buildSchemaFromType;
+    /**
+     * Extract JSDoc description from a property signature.
+     * Handles both /** comment * / style and // comment style.
+     */
+    private getPropertyJsDoc;
     /**
      * Convert TypeScript type node to JSON schema
      */
@@ -160,6 +165,52 @@ export declare class SchemaExtractor {
      * Indicates this method runs in background — returns execution ID immediately
      */
     private hasAsyncTag;
+    /**
+     * Extract @title tag value (human-readable display name)
+     * Example: @title Create New Task
+     */
+    private extractTitle;
+    /**
+     * Check if JSDoc contains method-level @readOnly tag (NOT param-level {@readOnly})
+     * Method-level: indicates tool has no side effects (MCP readOnlyHint)
+     * Param-level: {@readOnly} inside @param — different regex, no conflict
+     */
+    private hasReadOnlyHint;
+    /**
+     * Check if JSDoc contains @destructive tag
+     * Indicates tool performs destructive operations requiring confirmation
+     */
+    private hasDestructiveHint;
+    /**
+     * Check if JSDoc contains @idempotent tag
+     * Indicates tool is safe to retry — multiple calls produce same effect
+     */
+    private hasIdempotentHint;
+    /**
+     * Extract open/closed world hint from @openWorld or @closedWorld tags
+     * @openWorld → true (tool interacts with external systems)
+     * @closedWorld → false (tool operates only on local data)
+     * Returns undefined if neither tag present
+     */
+    private extractOpenWorldHint;
+    /**
+     * Extract @audience tag value
+     * @audience user → ['user']
+     * @audience assistant → ['assistant']
+     * @audience user assistant → ['user', 'assistant']
+     */
+    private extractAudience;
+    /**
+     * Extract @priority tag value (content importance 0.0-1.0)
+     */
+    private extractContentPriority;
+    /**
+     * Infer output schema from TypeScript return type annotation.
+     * Unwraps Promise<T> and converts T to JSON Schema.
+     * Property descriptions come from JSDoc on the type/interface properties.
+     * Only produces a schema for object return types (not primitives/arrays).
+     */
+    private inferOutputSchemaFromReturnType;
     /**
      * Extract notification subscriptions from @notify-on tag
      * Specifies which event types this photon is interested in
@@ -294,6 +345,15 @@ export declare class SchemaExtractor {
      * Note: Does NOT match @icon inside layout hints like {@icon fieldname}
      */
     private extractIcon;
+    /**
+     * Extract icon image entries from @icon (file path) and @icons tags
+     * @icon ./icons/calc.png          → [{ path: './icons/calc.png' }]
+     * @icon ./icons/calc.svg          → [{ path: './icons/calc.svg' }]
+     * @icons ./icons/calc-48.png 48x48       → [{ path: '...', sizes: '48x48' }]
+     * @icons ./icons/calc-dark.svg dark      → [{ path: '...', theme: 'dark' }]
+     * @icons ./icons/calc-96.png 96x96 dark  → [{ path: '...', sizes: '96x96', theme: 'dark' }]
+     */
+    private extractIconImages;
     /**
      * Extract MIME type from @mimeType tag
      * Example: @mimeType text/markdown

package/dist/schema-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../src/schema-extractor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../src/schema-extractor.ts"],"names":[],"mappings":"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"}

package/dist/schema-extractor.js

@@ -191,10 +191,20 @@ export class SchemaExtractor {
                     const layoutHints = this.extractLayoutHints(jsdoc);
                     const buttonLabel = this.extractButtonLabel(jsdoc);
                     const icon = this.extractIcon(jsdoc);
+                    const iconImages = this.extractIconImages(jsdoc);
                     const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
                     const isStateful = this.hasStatefulTag(jsdoc);
                     const autorun = this.hasAutorunTag(jsdoc);
                     const isAsync = this.hasAsyncTag(jsdoc);
+                    // MCP standard annotations
+                    const title = this.extractTitle(jsdoc);
+                    const readOnlyHint = this.hasReadOnlyHint(jsdoc);
+                    const destructiveHint = this.hasDestructiveHint(jsdoc);
+                    const idempotentHint = this.hasIdempotentHint(jsdoc);
+                    const openWorldHint = this.extractOpenWorldHint(jsdoc);
+                    const audience = this.extractAudience(jsdoc);
+                    const contentPriority = this.extractContentPriority(jsdoc);
+                    const outputSchema = this.inferOutputSchemaFromReturnType(member, sourceFile);
                     // Daemon features
                     const webhook = this.extractWebhook(jsdoc, methodName);
                     const scheduled = this.extractScheduled(jsdoc, methodName);
@@ -236,6 +246,7 @@ export class SchemaExtractor {
                         ...(layoutHints ? { layoutHints } : {}),
                         ...(buttonLabel ? { buttonLabel } : {}),
                         ...(icon ? { icon } : {}),
+                        ...(iconImages ? { iconImages } : {}),
                         ...(isGenerator ? { isGenerator: true } : {}),
                         ...(yields && yields.length > 0 ? { yields } : {}),
                         ...(isStateful ? { isStateful: true } : {}),
@@ -261,6 +272,15 @@ export class SchemaExtractor {
                         ...(deprecated !== undefined ? { deprecated } : {}),
                         // Unified middleware declarations (new — runtime uses this)
                         ...(middleware.length > 0 ? { middleware } : {}),
+                        // MCP standard annotations
+                        ...(title ? { title } : {}),
+                        ...(readOnlyHint ? { readOnlyHint: true } : {}),
+                        ...(destructiveHint ? { destructiveHint: true } : {}),
+                        ...(idempotentHint ? { idempotentHint: true } : {}),
+                        ...(openWorldHint !== undefined ? { openWorldHint } : {}),
+                        ...(audience ? { audience } : {}),
+                        ...(contentPriority !== undefined ? { contentPriority } : {}),
+                        ...(outputSchema ? { outputSchema } : {}),
                         // Event emission (for @stateful classes)
                         ...emitsEventData,
                     });
@@ -543,6 +563,11 @@ export class SchemaExtractor {
                     else {
                         properties[propName] = { type: 'object' };
                     }
+                    // Extract JSDoc description from property (e.g., /** Task ID */ id: string)
+                    const jsDocComment = this.getPropertyJsDoc(member, sourceFile);
+                    if (jsDocComment) {
+                        properties[propName].description = jsDocComment;
+                    }
                     // Add readonly from TypeScript (JSDoc can override)
                     if (isReadonly) {
                         properties[propName]._tsReadOnly = true;
@@ -552,6 +577,29 @@ export class SchemaExtractor {
         }
         return { properties, required };
     }
+    /**
+     * Extract JSDoc description from a property signature.
+     * Handles both /** comment * / style and // comment style.
+     */
+    getPropertyJsDoc(member, sourceFile) {
+        // Check for JSDoc comments attached to the node
+        const jsDocNodes = member.jsDoc;
+        if (jsDocNodes && jsDocNodes.length > 0) {
+            const comment = jsDocNodes[0].comment;
+            if (typeof comment === 'string')
+                return comment.trim();
+        }
+        // Fallback: look for leading comment in source text
+        const fullText = sourceFile.getFullText();
+        const start = member.getFullStart();
+        const leading = fullText.substring(start, member.getStart(sourceFile)).trim();
+        // Match /** ... */ or /* ... */
+        const blockMatch = leading.match(/\/\*\*?\s*([\s\S]*?)\s*\*\//);
+        if (blockMatch) {
+            return blockMatch[1].replace(/\s*\*\s*/g, ' ').trim();
+        }
+        return undefined;
+    }
     /**
      * Convert TypeScript type node to JSON schema
      */
@@ -665,6 +713,12 @@ export class SchemaExtractor {
                 resolved = node.type;
                 return;
             }
+            // Also resolve interface declarations → synthesize a TypeLiteral
+            if (ts.isInterfaceDeclaration(node) && node.name.text === typeName) {
+                // Create a synthetic TypeLiteralNode from interface members
+                resolved = ts.factory.createTypeLiteralNode(node.members.filter(ts.isPropertySignature));
+                return;
+            }
             ts.forEachChild(node, visit);
         };
         visit(sourceFile);
@@ -1529,6 +1583,114 @@ export class SchemaExtractor {
     hasAsyncTag(jsdocContent) {
         return /@async\b/i.test(jsdocContent);
     }
+    /**
+     * Extract @title tag value (human-readable display name)
+     * Example: @title Create New Task
+     */
+    extractTitle(jsdocContent) {
+        const match = jsdocContent.match(/@title\s+(.+?)(?:\n|\s*\*\/|\s*\*\s*@)/s);
+        if (match) {
+            return match[1].replace(/\s*\*\s*/g, ' ').trim();
+        }
+        return undefined;
+    }
+    /**
+     * Check if JSDoc contains method-level @readOnly tag (NOT param-level {@readOnly})
+     * Method-level: indicates tool has no side effects (MCP readOnlyHint)
+     * Param-level: {@readOnly} inside @param — different regex, no conflict
+     */
+    hasReadOnlyHint(jsdocContent) {
+        // Match @readOnly that is NOT inside curly braces (param-level uses {@readOnly})
+        // Look for @readOnly at start of line (after * ) or start of JSDoc
+        return /(?:^|\n)\s*\*?\s*@readOnly\b/m.test(jsdocContent);
+    }
+    /**
+     * Check if JSDoc contains @destructive tag
+     * Indicates tool performs destructive operations requiring confirmation
+     */
+    hasDestructiveHint(jsdocContent) {
+        return /@destructive\b/i.test(jsdocContent);
+    }
+    /**
+     * Check if JSDoc contains @idempotent tag
+     * Indicates tool is safe to retry — multiple calls produce same effect
+     */
+    hasIdempotentHint(jsdocContent) {
+        return /@idempotent\b/i.test(jsdocContent);
+    }
+    /**
+     * Extract open/closed world hint from @openWorld or @closedWorld tags
+     * @openWorld → true (tool interacts with external systems)
+     * @closedWorld → false (tool operates only on local data)
+     * Returns undefined if neither tag present
+     */
+    extractOpenWorldHint(jsdocContent) {
+        if (/@openWorld\b/i.test(jsdocContent))
+            return true;
+        if (/@closedWorld\b/i.test(jsdocContent))
+            return false;
+        return undefined;
+    }
+    /**
+     * Extract @audience tag value
+     * @audience user → ['user']
+     * @audience assistant → ['assistant']
+     * @audience user assistant → ['user', 'assistant']
+     */
+    extractAudience(jsdocContent) {
+        const match = jsdocContent.match(/@audience\s+([\w\s]+?)(?:\n|\s*\*\/|\s*\*\s*@)/);
+        if (match) {
+            const values = match[1].trim().split(/\s+/);
+            const valid = values.filter(v => v === 'user' || v === 'assistant');
+            return valid.length > 0 ? valid : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Extract @priority tag value (content importance 0.0-1.0)
+     */
+    extractContentPriority(jsdocContent) {
+        const match = jsdocContent.match(/@priority\s+([\d.]+)/);
+        if (match) {
+            const value = parseFloat(match[1]);
+            if (!isNaN(value) && value >= 0 && value <= 1) {
+                return value;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Infer output schema from TypeScript return type annotation.
+     * Unwraps Promise<T> and converts T to JSON Schema.
+     * Property descriptions come from JSDoc on the type/interface properties.
+     * Only produces a schema for object return types (not primitives/arrays).
+     */
+    inferOutputSchemaFromReturnType(method, sourceFile) {
+        const returnType = method.type;
+        if (!returnType)
+            return undefined;
+        // Unwrap Promise<T> → T
+        let innerType = returnType;
+        if (ts.isTypeReferenceNode(returnType)) {
+            const typeName = returnType.typeName.getText(sourceFile);
+            if (typeName === 'Promise' && returnType.typeArguments?.length) {
+                innerType = returnType.typeArguments[0];
+            }
+        }
+        // Convert to JSON Schema
+        const schema = this.typeNodeToSchema(innerType, sourceFile);
+        // Only produce outputSchema for object types with properties
+        if (schema.type === 'object' && schema.properties && Object.keys(schema.properties).length > 0) {
+            const result = {
+                type: 'object',
+                properties: schema.properties,
+            };
+            if (schema.required?.length)
+                result.required = schema.required;
+            return result;
+        }
+        return undefined;
+    }
     /**
      * Extract notification subscriptions from @notify-on tag
      * Specifies which event types this photon is interested in
@@ -1840,7 +2002,7 @@ export class SchemaExtractor {
             return subtype ? `chart:${subtype}` : 'chart';
         }
         // Match visualization formats
-        if (['metric', 'gauge', 'timeline', 'dashboard', 'cart'].includes(format)) {
+        if (['metric', 'gauge', 'timeline', 'dashboard', 'cart', 'qr'].includes(format)) {
             return format;
         }
         // Match container formats
@@ -1898,10 +2060,47 @@ export class SchemaExtractor {
         const withoutLayoutHints = jsdocContent.replace(/\{[^}]+\}/g, '');
         const iconMatch = withoutLayoutHints.match(/@icon\s+([^\s@*,]+)/i);
         if (iconMatch) {
-            return iconMatch[1].trim();
+            const value = iconMatch[1].trim();
+            // If it looks like a file path, don't return as emoji icon
+            if (value.startsWith('./') || value.startsWith('../') || /\.(png|jpg|jpeg|gif|svg|webp|ico)$/i.test(value)) {
+                return undefined;
+            }
+            return value;
         }
         return undefined;
     }
+    /**
+     * Extract icon image entries from @icon (file path) and @icons tags
+     * @icon ./icons/calc.png          → [{ path: './icons/calc.png' }]
+     * @icon ./icons/calc.svg          → [{ path: './icons/calc.svg' }]
+     * @icons ./icons/calc-48.png 48x48       → [{ path: '...', sizes: '48x48' }]
+     * @icons ./icons/calc-dark.svg dark      → [{ path: '...', theme: 'dark' }]
+     * @icons ./icons/calc-96.png 96x96 dark  → [{ path: '...', sizes: '96x96', theme: 'dark' }]
+     */
+    extractIconImages(jsdocContent) {
+        const images = [];
+        // Check if @icon value is a file path
+        const withoutLayoutHints = jsdocContent.replace(/\{[^}]+\}/g, '');
+        const iconMatch = withoutLayoutHints.match(/@icon\s+([^\s@*,]+)/i);
+        if (iconMatch) {
+            const value = iconMatch[1].trim();
+            if (value.startsWith('./') || value.startsWith('../') || /\.(png|jpg|jpeg|gif|svg|webp|ico)$/i.test(value)) {
+                images.push({ path: value });
+            }
+        }
+        // Extract @icons entries (can have multiple)
+        const iconsRegex = /@icons\s+([^\s@*,]+)(?:\s+(\d+x\d+))?(?:\s+(light|dark))?/gi;
+        let match;
+        while ((match = iconsRegex.exec(jsdocContent)) !== null) {
+            const entry = { path: match[1].trim() };
+            if (match[2])
+                entry.sizes = match[2];
+            if (match[3])
+                entry.theme = match[3];
+            images.push(entry);
+        }
+        return images.length > 0 ? images : undefined;
+    }
     /**
      * Extract MIME type from @mimeType tag
      * Example: @mimeType text/markdown