@matthesketh/fleet 1.8.1 → 1.11.0

package/dist/core/logs-policy.js

@@ -3,7 +3,7 @@
  * compose override file (.fleet/logging.override.yml) per app, plus journald
  * vacuum policy. Conservative defaults applied when unset.
  */
-import { existsSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { execSafe } from './exec.js';
 export const DEFAULT_POLICY = {
@@ -50,12 +50,31 @@ export function buildComposeOverride(app, policy) {
 export function overridePath(app) {
     return join(app.composePath, '.fleet', 'logging.override.yml');
 }
+/** ensure the app repo's .gitignore covers .fleet/ so the auto-generated
+ *  override file doesn't get committed accidentally. no-op when there's no
+ *  .gitignore (operator may be using a different vcs or none at all) and
+ *  idempotent — never appends a duplicate entry. */
+export function ensureFleetGitignored(composePath) {
+    const giPath = join(composePath, '.gitignore');
+    if (!existsSync(giPath))
+        return;
+    const current = readFileSync(giPath, 'utf-8');
+    // accept any of: .fleet, .fleet/, /.fleet, /.fleet/ — operators write all
+    // four forms.
+    if (/^\s*\/?\.fleet\/?\s*$/m.test(current))
+        return;
+    const append = current.endsWith('\n') ? '' : '\n';
+    writeFileSync(giPath, `${current}${append}\n# auto-added by fleet logs setup\n.fleet/\n`);
+}
 export function writeComposeOverride(app, policy) {
     const path = overridePath(app);
     const dir = dirname(path);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     writeFileSync(path, buildComposeOverride(app, policy));
+    // the override lands inside the operator's app repo. add .fleet/ to the
+    // app's .gitignore (if there is one) so it doesn't get committed.
+    ensureFleetGitignored(app.composePath);
     return path;
 }
 /** Best-effort docker-side log status. Uses `docker inspect` for driver + size. */

package/dist/core/operator.d.ts

@@ -0,0 +1,21 @@
+export interface OperatorConfig {
+    username: string;
+    homeDir: string;
+    domain: string;
+    githubOrg: string;
+}
+export type OperatorField = keyof OperatorConfig;
+export declare const OPERATOR_FIELDS: readonly OperatorField[];
+/** test-only: clears the memoised config. */
+export declare function _resetOperatorCache(): void;
+/** path the operator config is read from / written to. exported so the
+ *  fleet config command can print where it lives. */
+export declare function operatorPath(): string;
+/** loads operator identity from data/operator.json (gitignored, instance-local).
+ *  throws if the file is missing or incomplete — there is no safe default,
+ *  and guessing another operator's identity is never correct. */
+export declare function loadOperator(): OperatorConfig;
+/** persist the operator config to disk and clear the memoised copy so the
+ *  next loadOperator() picks up the new values. atomic write via .tmp +
+ *  rename so a crash mid-write never leaves a partial file behind. */
+export declare function saveOperator(cfg: OperatorConfig): void;

package/dist/core/operator.js

@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FleetError } from './errors.js';
+const here = dirname(fileURLToPath(import.meta.url));
+export const OPERATOR_FIELDS = ['username', 'homeDir', 'domain', 'githubOrg'];
+const FIELDS = OPERATOR_FIELDS;
+let cache = null;
+/** test-only: clears the memoised config. */
+export function _resetOperatorCache() { cache = null; }
+/** path the operator config is read from / written to. exported so the
+ *  fleet config command can print where it lives. */
+export function operatorPath() {
+    return process.env.FLEET_OPERATOR_PATH ?? join(here, '..', '..', 'data', 'operator.json');
+}
+/** loads operator identity from data/operator.json (gitignored, instance-local).
+ *  throws if the file is missing or incomplete — there is no safe default,
+ *  and guessing another operator's identity is never correct. */
+export function loadOperator() {
+    if (cache)
+        return cache;
+    const path = operatorPath();
+    if (!existsSync(path)) {
+        throw new FleetError(`operator config not found at ${path} — ` +
+            `copy data/operator.example.json to data/operator.json and fill it in`);
+    }
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    for (const field of FIELDS) {
+        if (!raw[field])
+            throw new FleetError(`operator config ${path} is missing field: ${field}`);
+    }
+    cache = raw;
+    return cache;
+}
+/** persist the operator config to disk and clear the memoised copy so the
+ *  next loadOperator() picks up the new values. atomic write via .tmp +
+ *  rename so a crash mid-write never leaves a partial file behind. */
+export function saveOperator(cfg) {
+    for (const field of FIELDS) {
+        if (typeof cfg[field] !== 'string' || cfg[field].length === 0) {
+            throw new FleetError(`operator config: ${field} must be a non-empty string`);
+        }
+    }
+    const path = operatorPath();
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+    // rename is atomic on the same filesystem; covers the crash-mid-write race
+    // a plain writeFileSync exposes.
+    renameSync(tmp, path);
+    cache = null;
+}

package/dist/core/registry.d.ts

@@ -61,3 +61,21 @@ export declare function findApp(reg: Registry, name: string): AppEntry | undefin
 export declare function addApp(reg: Registry, app: AppEntry): Registry;
 export declare function removeApp(reg: Registry, name: string): Registry;
 export declare function registryPath(): string;
+/**
+ * Run a read-modify-write transaction against the registry under an
+ * inter-process lock. The lock is held for the full load → mutate → save
+ * cycle, so concurrent CLI / cron / systemd / bot invocations don't lose
+ * each other's updates.
+ *
+ * The mutator may return a different Registry object (e.g. one returned by
+ * `addApp` / `removeApp`, which mutate in place but also return the registry
+ * for chaining) or simply mutate the input and return it. The returned value
+ * is what gets persisted.
+ *
+ * Returns void: callers needing the post-save state should re-load. Keeping
+ * this side-effecting matches how `load()` + `save()` are used today.
+ *
+ * Important: do not call this from inside another `withRegistry` block on the
+ * same process — proper-lockfile is not reentrant and will deadlock.
+ */
+export declare function withRegistry(fn: (reg: Registry) => Registry | Promise<Registry>): Promise<void>;

package/dist/core/registry.js

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync, mkdirSync, copyFileSync, renameSync, openSync, writeSync, fsyncSync, closeSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { withFileLock } from './file-lock.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function resolveRegistryPath() {
     return process.env.FLEET_REGISTRY_PATH
@@ -92,3 +93,28 @@ export function removeApp(reg, name) {
 export function registryPath() {
     return resolveRegistryPath();
 }
+/**
+ * Run a read-modify-write transaction against the registry under an
+ * inter-process lock. The lock is held for the full load → mutate → save
+ * cycle, so concurrent CLI / cron / systemd / bot invocations don't lose
+ * each other's updates.
+ *
+ * The mutator may return a different Registry object (e.g. one returned by
+ * `addApp` / `removeApp`, which mutate in place but also return the registry
+ * for chaining) or simply mutate the input and return it. The returned value
+ * is what gets persisted.
+ *
+ * Returns void: callers needing the post-save state should re-load. Keeping
+ * this side-effecting matches how `load()` + `save()` are used today.
+ *
+ * Important: do not call this from inside another `withRegistry` block on the
+ * same process — proper-lockfile is not reentrant and will deadlock.
+ */
+export async function withRegistry(fn) {
+    const path = resolveRegistryPath();
+    await withFileLock(path, async () => {
+        const reg = load();
+        const next = await fn(reg);
+        save(next);
+    });
+}

package/dist/core/routines/schema.d.ts

@@ -204,15 +204,14 @@ export declare const RoutineSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodString>;
     updatedAt: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    enabled: boolean;
     name: string;
+    enabled: boolean;
     id: string;
     notify: {
         config: Record<string, unknown>;
         kind: "email" | "stdout" | "webhook" | "slack";
         on: "always" | "failure" | "success";
     }[];
-    description: string;
     schedule: {
         kind: "manual";
     } | {
@@ -221,6 +220,8 @@ export declare const RoutineSchema: z.ZodObject<{
         randomizedDelaySec: number;
         persistent: boolean;
     };
+    tags: string[];
+    description: string;
     targets: string[];
     perTarget: boolean;
     task: {
@@ -244,7 +245,6 @@ export declare const RoutineSchema: z.ZodObject<{
         tool: string;
         args: Record<string, unknown>;
     };
-    tags: string[];
     updatedAt?: string | undefined;
     createdAt?: string | undefined;
 }, {
@@ -286,10 +286,10 @@ export declare const RoutineSchema: z.ZodObject<{
         config?: Record<string, unknown> | undefined;
         on?: "always" | "failure" | "success" | undefined;
     }[] | undefined;
+    tags?: string[] | undefined;
     description?: string | undefined;
     targets?: string[] | undefined;
     perTarget?: boolean | undefined;
-    tags?: string[] | undefined;
     createdAt?: string | undefined;
 }>;
 export type Routine = z.infer<typeof RoutineSchema>;
@@ -303,13 +303,13 @@ export declare const RunEventSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObjec
 }, "strip", z.ZodTypeAny, {
     at: string;
     kind: "start";
-    routineId: string;
     target: string | null;
+    routineId: string;
 }, {
     at: string;
     kind: "start";
-    routineId: string;
     target: string | null;
+    routineId: string;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"stdout">;
     chunk: z.ZodString;
@@ -370,14 +370,14 @@ export declare const RunEventSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObjec
     error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     at: string;
-    status: "timeout" | "ok" | "failed" | "aborted" | "queued" | "running";
+    status: "aborted" | "timeout" | "ok" | "queued" | "running" | "failed";
     kind: "end";
     exitCode: number;
     durationMs: number;
     error?: string | undefined;
 }, {
     at: string;
-    status: "timeout" | "ok" | "failed" | "aborted" | "queued" | "running";
+    status: "aborted" | "timeout" | "ok" | "queued" | "running" | "failed";
     kind: "end";
     exitCode: number;
     durationMs: number;
@@ -397,16 +397,16 @@ export declare const SignalSchema: z.ZodObject<{
     collectedAt: z.ZodString;
     ttlMs: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    detail: string;
-    kind: "git-clean" | "git-ahead" | "git-behind" | "open-prs" | "pr-age-max" | "deps-outdated" | "deps-vulns" | "build-ok" | "tests-ok" | "env-schema-ok" | "container-up" | "ci-status" | "cache-age";
     value: string | number | boolean | null;
+    kind: "git-clean" | "git-ahead" | "git-behind" | "open-prs" | "pr-age-max" | "deps-outdated" | "deps-vulns" | "build-ok" | "tests-ok" | "env-schema-ok" | "container-up" | "ci-status" | "cache-age";
+    detail: string;
     repo: string;
     state: "warn" | "error" | "unknown" | "ok";
     collectedAt: string;
     ttlMs: number;
 }, {
-    kind: "git-clean" | "git-ahead" | "git-behind" | "open-prs" | "pr-age-max" | "deps-outdated" | "deps-vulns" | "build-ok" | "tests-ok" | "env-schema-ok" | "container-up" | "ci-status" | "cache-age";
     value: string | number | boolean | null;
+    kind: "git-clean" | "git-ahead" | "git-behind" | "open-prs" | "pr-age-max" | "deps-outdated" | "deps-vulns" | "build-ok" | "tests-ok" | "env-schema-ok" | "container-up" | "ci-status" | "cache-age";
     repo: string;
     state: "warn" | "error" | "unknown" | "ok";
     collectedAt: string;

package/dist/core/routines/schema.js

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 const ROUTINE_ID_REGEX = /^[a-z][a-z0-9-]{0,62}$/;
 const NO_SHELL_META = /^[^`$;&|><\n\r\\"]*$/;
+// Printable ASCII only — no newlines, no control chars. Routine names and
+// descriptions are interpolated into systemd unit files; a newline would let
+// a hostile name inject directives like [Service]/User=root/ExecStart=…
+// that the systemd loader then runs as root after daemon-reload. Keep this
+// strict — widen explicitly if a future feature truly needs more.
+const ROUTINE_TEXT_REGEX = /^[\x20-\x7E]+$/;
+// systemd's documented OnCalendar grammar: weekdays, dates, times — all
+// printable ASCII without quotes, semicolons, control chars or newlines.
+// Same injection concern as above. Widen if "~" (last weekday) etc. is
+// actually needed.
+const ON_CALENDAR_REGEX = /^[A-Za-z0-9*\-/:., \t]+$/;
 const DEFAULT_WALLCLOCK_MS = 15 * 60 * 1000;
 const DEFAULT_TOKEN_CAP = 100_000;
 const DEFAULT_MAX_USD = 5;
@@ -38,15 +49,15 @@ export const RoutineScheduleSchema = z.union([
     z.object({ kind: z.literal('manual') }),
     z.object({
         kind: z.literal('calendar'),
-        onCalendar: z.string().min(1).max(200),
+        onCalendar: z.string().min(1).max(200).regex(ON_CALENDAR_REGEX, 'systemd OnCalendar tokens only (letters, digits, *-/:., space, tab)'),
         randomizedDelaySec: z.number().int().nonnegative().max(3600).default(0),
         persistent: z.boolean().default(true),
     }),
 ]);
 export const RoutineSchema = z.object({
     id: z.string().regex(ROUTINE_ID_REGEX, 'lowercase alphanumeric and dashes only'),
-    name: z.string().min(1).max(100),
-    description: z.string().max(2000).default(''),
+    name: z.string().min(1).max(100).regex(ROUTINE_TEXT_REGEX, 'printable ASCII only, no newlines or control chars'),
+    description: z.string().max(2000).regex(/^[\x20-\x7E]*$/, 'printable ASCII only, no newlines or control chars').default(''),
     schedule: RoutineScheduleSchema,
     enabled: z.boolean().default(true),
     targets: z.array(z.string().min(1)).default([]),

package/dist/core/routines/store.d.ts

@@ -109,15 +109,14 @@ declare const FileSchema: z.ZodObject<{
         createdAt: z.ZodOptional<z.ZodString>;
         updatedAt: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        enabled: boolean;
         name: string;
+        enabled: boolean;
         id: string;
         notify: {
             config: Record<string, unknown>;
             kind: "email" | "stdout" | "webhook" | "slack";
             on: "always" | "failure" | "success";
         }[];
-        description: string;
         schedule: {
             kind: "manual";
         } | {
@@ -126,6 +125,8 @@ declare const FileSchema: z.ZodObject<{
             randomizedDelaySec: number;
             persistent: boolean;
         };
+        tags: string[];
+        description: string;
         targets: string[];
         perTarget: boolean;
         task: {
@@ -149,7 +150,6 @@ declare const FileSchema: z.ZodObject<{
             tool: string;
             args: Record<string, unknown>;
         };
-        tags: string[];
         updatedAt?: string | undefined;
         createdAt?: string | undefined;
     }, {
@@ -191,25 +191,24 @@ declare const FileSchema: z.ZodObject<{
             config?: Record<string, unknown> | undefined;
             on?: "always" | "failure" | "success" | undefined;
         }[] | undefined;
+        tags?: string[] | undefined;
         description?: string | undefined;
         targets?: string[] | undefined;
         perTarget?: boolean | undefined;
-        tags?: string[] | undefined;
         createdAt?: string | undefined;
     }>, "many">;
     defaultsSeededAt: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     version: 1;
     routines: {
-        enabled: boolean;
         name: string;
+        enabled: boolean;
         id: string;
         notify: {
             config: Record<string, unknown>;
             kind: "email" | "stdout" | "webhook" | "slack";
             on: "always" | "failure" | "success";
         }[];
-        description: string;
         schedule: {
             kind: "manual";
         } | {
@@ -218,6 +217,8 @@ declare const FileSchema: z.ZodObject<{
             randomizedDelaySec: number;
             persistent: boolean;
         };
+        tags: string[];
+        description: string;
         targets: string[];
         perTarget: boolean;
         task: {
@@ -241,7 +242,6 @@ declare const FileSchema: z.ZodObject<{
             tool: string;
             args: Record<string, unknown>;
         };
-        tags: string[];
         updatedAt?: string | undefined;
         createdAt?: string | undefined;
     }[];
@@ -287,10 +287,10 @@ declare const FileSchema: z.ZodObject<{
             config?: Record<string, unknown> | undefined;
             on?: "always" | "failure" | "success" | undefined;
         }[] | undefined;
+        tags?: string[] | undefined;
         description?: string | undefined;
         targets?: string[] | undefined;
         perTarget?: boolean | undefined;
-        tags?: string[] | undefined;
         createdAt?: string | undefined;
     }[];
     defaultsSeededAt?: string | undefined;

package/dist/core/secrets-ops.d.ts

@@ -8,10 +8,15 @@ export declare function safeSealApp(app: string, content: string, sourceFile: st
 export declare function safeSealDbSecrets(app: string, secretsMap: Record<string, string>, sourceDir: string): SealValidation;
 export declare function setSecret(app: string, key: string, value: string, opts?: {
     allowWeak?: boolean;
-}): void;
+}): Promise<void>;
+/** read a single secret value. deliberately does NOT hold the manifest
+ *  lock — a concurrent setSecret/seal does an atomic file rename, so the
+ *  worst-case race here is reading the immediate-pre-rotation vault blob.
+ *  audit logging happens at the command layer so programmatic reads
+ *  (background sync, validation) don't pollute the audit trail. */
 export declare function getSecret(app: string, key: string): string | null;
-export declare function importEnvFile(app: string, path: string): number;
-export declare function importDbSecrets(app: string, dir: string): number;
+export declare function importEnvFile(app: string, path: string): Promise<number>;
+export declare function importDbSecrets(app: string, dir: string): Promise<number>;
 export declare function exportApp(app: string): string;
 export interface DriftResult {
     app: string;
@@ -22,12 +27,32 @@ export interface DriftResult {
 }
 export declare function detectDrift(app?: string): DriftResult[];
 export declare function unsealAll(): void;
-export declare function sealFromRuntime(app?: string): string[];
-export declare function rotateKey(): {
+export declare function sealFromRuntime(app?: string): Promise<string[]>;
+/**
+ * Rotate the age private key and re-encrypt every app's vault file with it.
+ *
+ * RECOVERY PROCEDURE (manual, only if rollback itself fails):
+ *   1. The previous private key is preserved at `<KEY_PATH>.old` while a
+ *      rotation is in flight. If you see that file lying around, a rotation
+ *      crashed mid-way.
+ *   2. Each app's pre-rotate encrypted file is preserved as
+ *      `vault/<app>.{env,secrets}.age.bak-rotate-<ts>` for the duration of
+ *      the rotation. They are removed automatically on success OR after a
+ *      successful rollback.
+ *   3. To restore by hand: copy `<KEY_PATH>.old` back to `<KEY_PATH>`
+ *      (chmod 0600), then for each `*.bak-rotate-<ts>` copy it over the
+ *      matching encrypted file. This puts the vault back into the
+ *      pre-rotation state.
+ *
+ * On a partial-failure path inside this function, that recovery is performed
+ * automatically before re-throwing. The whole rotation runs under the
+ * manifest's inter-process lock.
+ */
+export declare function rotateKey(): Promise<{
     oldPubkey: string;
     newPubkey: string;
     appsRotated: string[];
-};
+}>;
 export declare function getStatus(): {
     initialized: boolean;
     sealed: boolean;