@nettee/beacon 0.1.3 → 0.1.4

package/README.md

@@ -31,10 +31,11 @@ Upgrade to the current stable release with the same `latest` command. Run
 service. Beacon does not manage launchd installation, restart, or rollback in
 this release.
 
-Beacon only accepts an absolute path for the global configuration:
+Operator commands find the standard Beacon home automatically; a service
+deployment names its configuration explicitly:
 
 ```sh
-beacon doctor --config /Users/USERNAME/.beacon/config.yaml
+beacon doctor
 beacon serve --config /Users/USERNAME/.beacon/config.yaml
 ```
 
@@ -83,18 +84,37 @@ Each Schedule uses a five-field cron expression and an IANA timezone. Its `deliv
 
 ```text
 beacon serve --config <absolute-path>
-beacon doctor --config <absolute-path>
-beacon trigger --config <absolute-path> --profile <id> --input -
+beacon doctor [--config <absolute-path>]
+beacon trigger [--config <absolute-path>] --profile <id> --input -
+beacon schedule trigger [--config <absolute-path>] --profile <id> --schedule <id>
 beacon version
 ```
 
+Operator commands use `~/.beacon/config.yaml` when `--config` is omitted.
+An explicit override must still be an absolute path. `serve` keeps requiring an
+explicit absolute config path so service definitions identify their deployment
+configuration unambiguously.
+
 An operator can run one Profile without Feishu delivery by piping input to `trigger`; the Final Outcome is printed to stdout:
 
 ```sh
 printf '%s\n' 'Summarize the workspace status.' | \
-  beacon trigger --config /Users/USERNAME/.beacon/config.yaml --profile example --input -
+  beacon trigger --profile example --input -
+```
+
+An operator can also immediately run a configured Schedule through the real
+Schedule input and Feishu chat Delivery path:
+
+```sh
+beacon schedule trigger --profile example --schedule daily-report
 ```
 
+This creates a distinct durable Run on every invocation and prints its
+`run_id`. It uses the Schedule's configured `input` and `delivery.chat_id`, but
+does not read, initialize, or advance the Schedule's cron cursor. Unknown
+Profiles or Schedules and failed Runs or Deliveries exit non-zero; failure
+messages include the `run_id` whenever a Run record was created.
+
 ## State and failure behavior
 
 Per-Profile state lives below `profiles/<profile-id>/state/`. Trigger claims, normalized inputs, Run state, Final Outcomes, Delivery state, and Schedule cursors use durable JSON snapshots. Records do not expire, and Beacon has no automatic cleanup task. Manually deleting state also deletes its deduplication memory.
@@ -143,6 +163,12 @@ launchctl print gui/$(id -u)/io.nettee.beacon
 
 The example uses a restrictive umask and asks launchd to restart only after abnormal exit. `SIGTERM` initiates an orderly shutdown: timers and Gateways stop, accepted intake work drains, and the local Outcome server closes.
 
+The repository also contains Chinese operator runbooks based on the verified
+`macmini.liuyi` deployment:
+
+- [Deploy or update Beacon on macmini](docs/macmini-deploy-and-update.md)
+- [Add a Beacon Profile on macmini](docs/macmini-add-profile.md)
+
 ## Development checks
 
 Development requires pnpm 10.33.2. Install dependencies before running checks

package/dist/cli-app.js

@@ -1,18 +1,40 @@
-import { isAbsolute } from "node:path";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+export const defaultConfigPath = join(homedir(), ".beacon", "config.yaml");
 function usage() {
     throw new Error(`Usage:
   beacon serve --config <absolute-path>
-  beacon doctor --config <absolute-path>
-  beacon trigger --config <absolute-path> --profile <id> --input -
+  beacon doctor [--config <absolute-path>]
+  beacon trigger [--config <absolute-path>] --profile <id> --input -
+  beacon schedule trigger [--config <absolute-path>] --profile <id> --schedule <id>
   beacon version`);
 }
-function configOnly(args) {
+function requiredConfig(args) {
     if (args.length !== 2 || args[0] !== "--config" || !args[1])
         usage();
     if (!isAbsolute(args[1]))
         throw new Error("Config path must be absolute");
     return args[1];
 }
+function options(args) {
+    if (args.length % 2 !== 0)
+        usage();
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 2) {
+        const key = args[index];
+        const value = args[index + 1];
+        if (!key?.startsWith("--") || !value || values.has(key))
+            usage();
+        values.set(key, value);
+    }
+    return values;
+}
+function optionalConfig(values) {
+    const config = values.get("--config") ?? defaultConfigPath;
+    if (!isAbsolute(config))
+        throw new Error("Config path must be absolute");
+    return config;
+}
 export function parseCli(args) {
     const [command, ...rest] = args;
     if (command === "version") {
@@ -20,30 +42,38 @@ export function parseCli(args) {
             usage();
         return { command: "version" };
     }
-    if (command === "serve" || command === "doctor") {
-        return { command, config: configOnly(rest) };
+    if (command === "serve") {
+        return { command, config: requiredConfig(rest) };
     }
-    if (command === "trigger") {
-        if (rest.length !== 6)
+    if (command === "doctor") {
+        const values = options(rest);
+        if ([...values.keys()].some((key) => key !== "--config"))
             usage();
-        const values = new Map();
-        for (let index = 0; index < rest.length; index += 2) {
-            const key = rest[index];
-            const value = rest[index + 1];
-            if (!key?.startsWith("--") || !value || values.has(key))
-                usage();
-            values.set(key, value);
-        }
-        const config = values.get("--config");
+        return { command, config: optionalConfig(values) };
+    }
+    if (command === "trigger") {
+        const values = options(rest);
         const profile = values.get("--profile");
-        if (!config ||
-            !profile ||
+        if (!profile ||
             values.get("--input") !== "-" ||
-            values.size !== 3)
+            [...values.keys()].some((key) => !["--config", "--profile", "--input"].includes(key)))
+            usage();
+        return { command: "trigger", config: optionalConfig(values), profile };
+    }
+    if (command === "schedule" && rest[0] === "trigger") {
+        const values = options(rest.slice(1));
+        const profile = values.get("--profile");
+        const schedule = values.get("--schedule");
+        if (!profile ||
+            !schedule ||
+            [...values.keys()].some((key) => !["--config", "--profile", "--schedule"].includes(key)))
             usage();
-        if (!isAbsolute(config))
-            throw new Error("Config path must be absolute");
-        return { command: "trigger", config, profile };
+        return {
+            command: "schedule-trigger",
+            config: optionalConfig(values),
+            profile,
+            schedule,
+        };
     }
     if (command === "outcome" && rest.length === 1 && rest[0] === "submit") {
         return { command: "outcome-submit" };
@@ -65,6 +95,9 @@ export async function runCli(command, dependencies) {
     if (command.command === "trigger") {
         return dependencies.trigger(command.config, command.profile, await readStdin());
     }
+    if (command.command === "schedule-trigger") {
+        return dependencies.triggerSchedule(command.config, command.profile, command.schedule);
+    }
     if (command.command === "outcome-submit")
         return dependencies.submitOutcome();
     console.log(dependencies.version);

package/dist/cli.js

@@ -3,6 +3,7 @@ import { parseCli, runCli } from "./cli-app.js";
 import { runDoctor } from "./doctor.js";
 import { runManualTrigger } from "./manual-trigger.js";
 import { submitOutcomeFromCli } from "./outcome/submit.js";
+import { runScheduleTrigger } from "./schedule-trigger.js";
 import { runBeacon } from "./service.js";
 import { packageVersion } from "./version.js";
 async function main() {
@@ -10,6 +11,7 @@ async function main() {
         serve: runBeacon,
         doctor: runDoctor,
         trigger: runManualTrigger,
+        triggerSchedule: runScheduleTrigger,
         submitOutcome: submitOutcomeFromCli,
         version: packageVersion,
     });

package/dist/schedule-trigger.js

@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { loadGlobalConfig } from "./config/global.js";
+import { loadProfileRegistry } from "./config/registry.js";
+import { loadFeishuCredentials } from "./config/secrets.js";
+import { createFeishuGateway } from "./feishu/gateway.js";
+import { startOutcomeServer } from "./outcome/server.js";
+import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
+import { RunQueue } from "./run/queue.js";
+import { TriggerStore } from "./state/trigger-store.js";
+function findSchedule(profile, scheduleId) {
+    const schedule = profile.schedules.find((candidate) => candidate.id === scheduleId);
+    if (!schedule) {
+        throw new Error(`Unknown Schedule in Profile ${profile.id}: ${scheduleId}`);
+    }
+    return schedule;
+}
+export async function triggerScheduleOnce(options) {
+    const schedule = findSchedule(options.profile, options.scheduleId);
+    const scheduledFor = (options.now ?? (() => new Date()))().toISOString();
+    const invocationId = (options.id ?? randomUUID)();
+    const claim = await options.store.claim({
+        sourceKey: ["manual-schedule", schedule.id, invocationId],
+        target: { kind: "chat", chatId: schedule.delivery.chatId },
+        ingress: {
+            invocation: "manual",
+            scheduleId: schedule.id,
+            scheduledFor,
+            text: schedule.input,
+        },
+    });
+    if (!claim.created) {
+        throw new Error(`Duplicate manual Schedule invocation: ${invocationId}`);
+    }
+    await options.process(claim.record.triggerKey, async () => ({
+        kind: "schedule",
+        scheduleId: schedule.id,
+        scheduledFor,
+        text: schedule.input,
+    }));
+    const record = (await options.store.list()).find((candidate) => candidate.triggerKey === claim.record.triggerKey);
+    if (!record?.run) {
+        throw new Error(`Schedule Trigger produced no Run record: trigger_id=${claim.record.triggerId}`);
+    }
+    if (record.run.state !== "succeeded" ||
+        record.delivery?.state !== "delivered") {
+        const failure = record.run.failure?.code ?? record.delivery?.failure?.code ?? "unknown";
+        throw new Error(`Schedule Trigger failed (run_id=${record.run.runId}): ${failure}`);
+    }
+    return record;
+}
+export async function runScheduleTrigger(configPath, profileId, scheduleId) {
+    const global = await loadGlobalConfig(configPath);
+    const profiles = await loadProfileRegistry(global.profilesDirectory);
+    const profile = profiles.find((candidate) => candidate.id === profileId);
+    if (!profile)
+        throw new Error(`Unknown Profile: ${profileId}`);
+    findSchedule(profile, scheduleId);
+    const credentials = await loadFeishuCredentials(profile.id, global.secretsPath);
+    const outcomes = await startOutcomeServer();
+    try {
+        const store = new TriggerStore(profile.directory, profile.id);
+        const orchestrator = createPiRunOrchestrator({
+            config: global,
+            profile,
+            store,
+            queue: new RunQueue(global.runs.maxConcurrent, global.runs.maxQueued),
+            outcomes,
+            delivery: createFeishuGateway(credentials),
+        });
+        const record = await triggerScheduleOnce({
+            profile,
+            scheduleId,
+            store,
+            process: (triggerKey, normalize) => orchestrator.process(triggerKey, normalize),
+        });
+        console.log(`[beacon] Schedule Trigger succeeded run_id=${record.run.runId}`);
+    }
+    finally {
+        await outcomes.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nettee/beacon",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A single-host bridge from messaging and schedules to isolated agent runs",
   "license": "Apache-2.0",
   "repository": {