ghostrail 0.8.0 → 0.10.0

package/dist/dashboard/routes.js

@@ -0,0 +1,102 @@
+/** Map a request pathname to a route. Total; never throws. */
+export function parseDashboardRoute(pathname) {
+    const parts = pathname.split("/").filter((p) => p.length > 0);
+    // Nothing but slashes is the root. `//` reaching a server is unusual but a
+    // proxy or a hand-built link produces it, and serving the page beats a 404
+    // for something that means the root by every reading.
+    if (parts.length === 0)
+        return { kind: "page" };
+    if (parts[0] !== "api" || parts.length !== 2)
+        return { kind: "notfound" };
+    if (parts[1] === "ghostrails")
+        return { kind: "ghostrails" };
+    if (parts[1] === "watch")
+        return { kind: "watch" };
+    return { kind: "notfound" };
+}
+/**
+ * Every value for a header, case-insensitively.
+ *
+ * All of them, not the first. Node hands back an array for a repeated header,
+ * and a guard that inspects only `value[0]` can be walked past by sending the
+ * innocent spelling first. For a check whose whole job is refusing a request,
+ * "any value looks like an attack" is the only safe reading.
+ *
+ * Case-insensitive on the name because Node lowercases them but a hand-built
+ * object does not have to.
+ */
+function headerValues(headers, name) {
+    const wanted = name.toLowerCase();
+    const values = [];
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== wanted || value === undefined)
+            continue;
+        if (Array.isArray(value))
+            values.push(...value);
+        else
+            values.push(String(value));
+    }
+    return values;
+}
+/** The three content types a form can send without a CORS preflight. */
+const FORM_TYPES = ["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"];
+/**
+ * True when a request looks cross-origin, which the write route refuses.
+ *
+ * This is not the token decision (TJ-1554 owns that). It is hygiene for a
+ * mutating route: a plain HTML form on any website can POST to a loopback port
+ * cross-origin, and by inherited board behaviour there is no token in the way
+ * unless the bind is non-loopback. Without this, any page the operator visits
+ * could flip their watch flags.
+ *
+ * A request with neither signal, such as `curl` sending JSON, is allowed.
+ * Locking that out is a token's job: anything able to set arbitrary headers can
+ * also read a token, so refusing it would break scripting for no gain.
+ */
+export function isCrossOriginWrite(headers) {
+    // Browsers send this unconditionally and script cannot forge it. Any value
+    // that is not same-origin rejects, so a repeated header cannot smuggle one
+    // past by leading with the innocent spelling.
+    const sites = headerValues(headers, "sec-fetch-site");
+    if (sites.some((site) => site.trim().toLowerCase() !== "same-origin"))
+        return true;
+    // Requiring a non-form content type forces a preflight a form cannot satisfy.
+    return headerValues(headers, "content-type").some((value) => {
+        const media = value.split(";")[0]?.trim().toLowerCase() ?? "";
+        return FORM_TYPES.includes(media);
+    });
+}
+/** True if `value` is a plain object (not null, not an array). */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse the write body: `{ path, watch }`. Undefined for anything else, which
+ * the route answers with 400.
+ *
+ * An empty `path` is rejected rather than passed through: it can never match a
+ * registered ghostrail, so accepting it would only produce a confusing 404.
+ */
+/**
+ * Unknown keys alongside the two it needs are ignored, and the entry still
+ * parses. Same forward compatibility the registry uses: a later dashboard that
+ * sends an extra field must not make an older server reject the write outright.
+ */
+export function parseWatchUpdate(body) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const { path, watch } = value;
+    if (typeof path !== "string" || path.length === 0)
+        return undefined;
+    if (typeof watch !== "boolean")
+        return undefined;
+    return { path, watch };
+}
+//# sourceMappingURL=routes.js.map

package/dist/dashboard/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/dashboard/routes.ts"],"names":[],"mappings":"AAcA,8DAA8D;AAC9D,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9D,2EAA2E;IAC3E,2EAA2E;IAC3E,sDAAsD;IACtD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAChD,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC1E,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAC7D,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACnD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,YAAY,CAAC,OAA4B,EAAE,IAAY;IAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,MAAM,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;;YAC3C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,GAAG,CAAC,mCAAmC,EAAE,qBAAqB,EAAE,YAAY,CAAC,CAAC;AAE9F;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,2EAA2E;IAC3E,2EAA2E;IAC3E,8CAA8C;IAC9C,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnF,8EAA8E;IAC9E,OAAO,YAAY,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;QAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAClE,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACpE,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/dashboard/server.d.ts

@@ -0,0 +1,43 @@
+import { type Server } from "node:http";
+import type { Ghostrail } from "../global/registry.js";
+/** How a ghostrail stands on disk, mirroring what `status` reports. */
+export type GhostrailHealth = "ok" | "no config" | "missing";
+/** One row of the dashboard: registry entry plus everything observed about it. */
+export interface GhostrailView extends Ghostrail {
+    health: GhostrailHealth;
+    /** Live unit state, e.g. `active`. `unknown` when no manager could be asked. */
+    state: string;
+    /** Most recent runs from this ghostrail's own `.factory`, newest first. */
+    runs: {
+        runId: string;
+        itemId?: string;
+        state?: string;
+        title?: string;
+    }[];
+}
+/** Everything the server needs, injected so it can be driven without a machine. */
+export interface DashboardDeps {
+    /** The registry, or undefined when it could not be parsed. */
+    readRegistry(): Promise<Ghostrail[] | undefined>;
+    writeRegistry(entries: readonly Ghostrail[]): Promise<void>;
+    health(path: string): Promise<GhostrailHealth>;
+    /** Live unit state per ghostrail path. */
+    states(entries: readonly Ghostrail[]): Promise<Map<string, string>>;
+}
+export interface DashboardOptions {
+    bind?: string;
+    /** When set, every request must present it. Inherited from the board's behaviour. */
+    token?: string;
+}
+/** Assemble the view for every registered ghostrail. */
+export declare function collectViews(deps: DashboardDeps, entries: readonly Ghostrail[]): Promise<GhostrailView[]>;
+/**
+ * The dashboard's HTTP server: one page, one listing, and one write route that
+ * sets a ghostrail's `watch` flag and does nothing else.
+ *
+ * It never starts or stops anything. `start` and the service units act on the
+ * flag, which keeps process control off an HTTP surface: the worst a
+ * compromised dashboard can do is change which ghostrails come up next time.
+ */
+export declare function createDashboardServer(deps: DashboardDeps, options?: DashboardOptions): Server;
+//# sourceMappingURL=server.d.ts.map

package/dist/dashboard/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/dashboard/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAqC,MAAM,WAAW,CAAC;AAE3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKvD,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7D,kFAAkF;AAClF,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,MAAM,EAAE,eAAe,CAAC;IACxB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5E;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC;IACjD,aAAa,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC/C,0CAA0C;IAC1C,MAAM,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0BD,wDAAwD;AACxD,wBAAsB,YAAY,CAChC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,SAAS,SAAS,EAAE,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CAwB1B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAsDjG"}

package/dist/dashboard/server.js

@@ -0,0 +1,110 @@
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { FileStore } from "../store/file-store.js";
+import { DASHBOARD_PAGE_HTML } from "./page.js";
+import { isCrossOriginWrite, parseDashboardRoute, parseWatchUpdate } from "./routes.js";
+/** The store dir inside a ghostrail. */
+const STORE_DIR = ".factory";
+/** How many runs to show per ghostrail. Enough to see recent activity, not a log. */
+const RUNS_PER_GHOSTRAIL = 5;
+function sendJson(res, status, data) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(data));
+}
+/** Read a request body, bounded so a stray large POST cannot exhaust memory. */
+async function readBody(req, limit = 64 * 1024) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buf.length;
+        if (size > limit)
+            break;
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** Assemble the view for every registered ghostrail. */
+export async function collectViews(deps, entries) {
+    const states = await deps.states(entries);
+    const views = [];
+    for (const entry of entries) {
+        const health = await deps.health(entry.path);
+        // A ghostrail with no .factory yet is still a ghostrail; it just has
+        // nothing to report. Never let a missing store turn a row into an error.
+        let runs = [];
+        if (health === "ok") {
+            try {
+                const rows = await new FileStore(join(entry.path, STORE_DIR)).listRuns({});
+                runs = rows.slice(0, RUNS_PER_GHOSTRAIL).map((row) => ({
+                    runId: row.runId,
+                    ...(row.itemId === undefined ? {} : { itemId: row.itemId }),
+                    ...(row.state === undefined ? {} : { state: row.state }),
+                    ...(row.title === undefined ? {} : { title: row.title }),
+                }));
+            }
+            catch {
+                runs = [];
+            }
+        }
+        views.push({ ...entry, health, state: states.get(entry.path) ?? "unknown", runs });
+    }
+    return views;
+}
+/**
+ * The dashboard's HTTP server: one page, one listing, and one write route that
+ * sets a ghostrail's `watch` flag and does nothing else.
+ *
+ * It never starts or stops anything. `start` and the service units act on the
+ * flag, which keeps process control off an HTTP surface: the worst a
+ * compromised dashboard can do is change which ghostrails come up next time.
+ */
+export function createDashboardServer(deps, options = {}) {
+    return createServer((req, res) => {
+        void (async () => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (options.token !== undefined) {
+                const presented = req.headers["x-ghostrail-token"] ?? url.searchParams.get("token") ?? "";
+                if (presented !== options.token)
+                    return sendJson(res, 401, { error: "unauthorized" });
+            }
+            const route = parseDashboardRoute(url.pathname);
+            if (route.kind === "page") {
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                return res.end(DASHBOARD_PAGE_HTML);
+            }
+            const entries = await deps.readRegistry();
+            if (entries === undefined) {
+                return sendJson(res, 500, { error: "the ghostrails registry could not be parsed" });
+            }
+            if (route.kind === "ghostrails") {
+                return sendJson(res, 200, { ghostrails: await collectViews(deps, entries) });
+            }
+            if (route.kind === "watch") {
+                if (req.method !== "POST")
+                    return sendJson(res, 405, { error: "use POST" });
+                // Hygiene for a mutating route, not the token decision (TJ-1554). A
+                // form on any site can POST here cross-origin, and by inherited board
+                // behaviour there is no token in the way on loopback.
+                if (isCrossOriginWrite(req.headers)) {
+                    return sendJson(res, 403, { error: "cross-origin writes are refused" });
+                }
+                const update = parseWatchUpdate(await readBody(req));
+                if (update === undefined) {
+                    return sendJson(res, 400, { error: "expected {path: string, watch: boolean}" });
+                }
+                // Must already be registered. Registering an arbitrary filesystem path
+                // over HTTP is a far larger surface than this route wants to be, and
+                // registration is `init`'s job.
+                if (!entries.some((e) => e.path === update.path)) {
+                    return sendJson(res, 404, { error: "no registered ghostrail at that path" });
+                }
+                const next = entries.map((e) => e.path === update.path ? { ...e, watch: update.watch } : e);
+                await deps.writeRegistry(next);
+                return sendJson(res, 200, { ghostrails: await collectViews(deps, next) });
+            }
+            return sendJson(res, 404, { error: "not found" });
+        })().catch(() => sendJson(res, 500, { error: "internal error" }));
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/dashboard/server.js.map

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

package/dist/global/index.d.ts

@@ -1,3 +1,4 @@
+export { type Ghostrail, REGISTRY_FILE, findByPath, parseRegistry, renderRegistry, upsert, } from "./registry.js";
 export { artifactFileName, type GlobalEnv, GlobalStore, resolveGlobalDir } from "./store.js";
 export { STAGED_ARTIFACTS_DIR, stageArtifacts } from "./stage.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/global/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/global/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/global/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,aAAa,EACb,UAAU,EACV,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/global/index.js

@@ -1,3 +1,4 @@
+export { REGISTRY_FILE, findByPath, parseRegistry, renderRegistry, upsert, } from "./registry.js";
 export { artifactFileName, GlobalStore, resolveGlobalDir } from "./store.js";
 export { STAGED_ARTIFACTS_DIR, stageArtifacts } from "./stage.js";
 //# sourceMappingURL=index.js.map

package/dist/global/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/global/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAkB,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/global/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EACb,UAAU,EACV,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAkB,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/global/registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The registry of ghostrails: which repos this account has set up, so
+ * `start` has something to offer and the board has something to list. Lives
+ * beside `settings.toml` in the global dir.
+ *
+ * Everything here is pure. Reading and writing the file is the store's job, so
+ * a malformed registry can be tested without a filesystem.
+ */
+/** One repo ghostrail knows about. */
+export interface Ghostrail {
+    /** Display name, from `[factory].name` or the directory. Never an identity. */
+    name: string;
+    /** Absolute path to the repo. This is the identity. */
+    path: string;
+    /** ISO date the entry was added, for the operator. Nothing reads it. */
+    added: string;
+    /**
+     * Desired state: whether `start` should bring this one up. Not live state.
+     * One flag, so the CLI, the board, and the service units cannot disagree.
+     */
+    watch: boolean;
+}
+/** The file name in the global dir. */
+export declare const REGISTRY_FILE = "ghostrails.toml";
+/**
+ * Parse the registry, or undefined when it cannot be trusted.
+ *
+ * All or nothing, exactly as `readManifest` treats a malformed manifest: a
+ * half-trusted registry is worse than none, because silently dropping one bad
+ * entry would quietly stop watching a ghostrail with no signal that anything
+ * was wrong.
+ *
+ * A file with no `[[ghostrail]]` array is an empty registry, not a broken one:
+ * nothing registered yet is a real state, and so is an explicitly empty
+ * `ghostrail = []`. Unknown keys on an otherwise valid entry are ignored rather
+ * than fatal, so a registry written by a later ghostrail still reads here.
+ * Order is preserved exactly, and the array is fresh on every call.
+ *
+ * Two entries at the same path are malformed for the same reason: a parsed
+ * registry never contains duplicate paths, which is what lets `upsert` and
+ * `findByPath` stay as simple as they are.
+ */
+export declare function parseRegistry(toml: string): Ghostrail[] | undefined;
+/**
+ * Render entries back to TOML, in the order given. Round-trips through
+ * {@link parseRegistry}, which is what keeps a rewrite from mangling a file the
+ * operator has edited.
+ *
+ * The layout is part of the contract: keys padded so the `=` signs line up, one
+ * blank line between blocks. Both are for the human who opens this file, which
+ * the header invites them to do.
+ */
+export declare function renderRegistry(entries: readonly Ghostrail[]): string;
+/** The entry at `path`, or undefined. Exact string equality; callers resolve first. */
+export declare function findByPath(entries: readonly Ghostrail[], path: string): Ghostrail | undefined;
+/**
+ * Add `entry`, or replace the one at the same path.
+ *
+ * A replacement keeps its position so a diff of the file shows a changed block
+ * rather than a move; a new entry appends. Neither argument is mutated.
+ */
+export declare function upsert(entries: readonly Ghostrail[], entry: Ghostrail): Ghostrail[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/global/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/global/registry.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,uCAAuC;AACvC,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAyB/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAS,CA2BnE;AAOD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAapE;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAMnF"}

package/dist/global/registry.js

@@ -0,0 +1,120 @@
+import { parse as parseToml } from "smol-toml";
+/** The file name in the global dir. */
+export const REGISTRY_FILE = "ghostrails.toml";
+const HEADER = `# The ghostrails this account knows about: the repos ghostrail is set up for.
+#
+# Written by \`ghostrail init\` and topped up by \`ghostrail init --update\`.
+# \`watch\` is desired state, what \`ghostrail start\` should bring up, not a
+# statement about what is running right now.
+#
+# Safe to hand-edit. A file that does not parse is treated as no registry at
+# all rather than half-trusted, so a typo here is loud, not silent.`;
+/** True if `value` is a plain object (not null, not an array). */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One entry, or undefined if any required field is missing or wrong-typed. */
+function parseEntry(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const { name, path, added, watch } = raw;
+    if (typeof name !== "string" || typeof path !== "string")
+        return undefined;
+    if (typeof added !== "string" || typeof watch !== "boolean")
+        return undefined;
+    return { name, path, added, watch };
+}
+/**
+ * Parse the registry, or undefined when it cannot be trusted.
+ *
+ * All or nothing, exactly as `readManifest` treats a malformed manifest: a
+ * half-trusted registry is worse than none, because silently dropping one bad
+ * entry would quietly stop watching a ghostrail with no signal that anything
+ * was wrong.
+ *
+ * A file with no `[[ghostrail]]` array is an empty registry, not a broken one:
+ * nothing registered yet is a real state, and so is an explicitly empty
+ * `ghostrail = []`. Unknown keys on an otherwise valid entry are ignored rather
+ * than fatal, so a registry written by a later ghostrail still reads here.
+ * Order is preserved exactly, and the array is fresh on every call.
+ *
+ * Two entries at the same path are malformed for the same reason: a parsed
+ * registry never contains duplicate paths, which is what lets `upsert` and
+ * `findByPath` stay as simple as they are.
+ */
+export function parseRegistry(toml) {
+    let root;
+    try {
+        root = parseToml(toml);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(root))
+        return undefined;
+    const raw = root.ghostrail;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return undefined;
+    const entries = [];
+    const paths = new Set();
+    for (const item of raw) {
+        const entry = parseEntry(item);
+        if (entry === undefined)
+            return undefined;
+        // `path` is the identity, so two blocks claiming it is a contradiction
+        // rather than a preference to resolve. Copying a block and forgetting to
+        // change the path is a plausible hand-edit, and honouring either one of
+        // them would silently ignore an edit the operator clearly meant.
+        if (paths.has(entry.path))
+            return undefined;
+        paths.add(entry.path);
+        entries.push(entry);
+    }
+    return entries;
+}
+/** TOML-quote a string. The values here are paths and names, not arbitrary data. */
+function quote(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Render entries back to TOML, in the order given. Round-trips through
+ * {@link parseRegistry}, which is what keeps a rewrite from mangling a file the
+ * operator has edited.
+ *
+ * The layout is part of the contract: keys padded so the `=` signs line up, one
+ * blank line between blocks. Both are for the human who opens this file, which
+ * the header invites them to do.
+ */
+export function renderRegistry(entries) {
+    const blocks = entries.map((entry) => [
+        "[[ghostrail]]",
+        `name  = ${quote(entry.name)}`,
+        `path  = ${quote(entry.path)}`,
+        `added = ${quote(entry.added)}`,
+        `watch = ${entry.watch}`,
+    ].join("\n"));
+    // A blank line between blocks. This file is advertised as hand-editable, and
+    // run together the blocks are hard to read and give noisier diffs.
+    return `${[HEADER, ...blocks].join("\n\n")}\n`;
+}
+/** The entry at `path`, or undefined. Exact string equality; callers resolve first. */
+export function findByPath(entries, path) {
+    return entries.find((entry) => entry.path === path);
+}
+/**
+ * Add `entry`, or replace the one at the same path.
+ *
+ * A replacement keeps its position so a diff of the file shows a changed block
+ * rather than a move; a new entry appends. Neither argument is mutated.
+ */
+export function upsert(entries, entry) {
+    const index = entries.findIndex((existing) => existing.path === entry.path);
+    if (index === -1)
+        return [...entries, entry];
+    const next = [...entries];
+    next[index] = entry;
+    return next;
+}
+//# sourceMappingURL=registry.js.map

package/dist/global/registry.js.map

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

package/dist/global/store.d.ts

@@ -1,3 +1,4 @@
+import { type Ghostrail } from "./registry.js";
 export interface GlobalEnv {
     GHOSTRAIL_HOME?: string;
     XDG_CONFIG_HOME?: string;
@@ -24,6 +25,15 @@ export declare class GlobalStore {
     readSettings(): Promise<string | undefined>;
     /** Artifact base names present in the store, sorted. */
     listArtifacts(): Promise<string[]>;
+    registryPath(): string;
+    /**
+     * The registered ghostrails. `undefined` means the file exists but could not
+     * be trusted, which is deliberately different from `[]` (nothing registered
+     * yet): a caller must be able to tell "broken" from "empty" so it can say so.
+     */
+    readRegistry(): Promise<Ghostrail[] | undefined>;
+    /** Write the registry, creating the global dir if this is the first entry. */
+    writeRegistry(entries: readonly Ghostrail[]): Promise<void>;
     /** An artifact's contents by name (with or without `.md`), or undefined. */
     readArtifact(name: string): Promise<string | undefined>;
 }

package/dist/global/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/global/store.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxE;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,EAAE,MAAM;IAIvB,YAAY,IAAI,MAAM;IAItB,mEAAmE;IAC7D,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQjD,wDAAwD;IAClD,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQxC,4EAA4E;IACtE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAU9D"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/global/store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAgD,MAAM,eAAe,CAAC;AAE7F,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxE;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,EAAE,MAAM;IAIvB,YAAY,IAAI,MAAM;IAItB,mEAAmE;IAC7D,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQjD,wDAAwD;IAClD,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQxC,YAAY,IAAI,MAAM;IAItB;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC;IAUtD,8EAA8E;IACxE,aAAa,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,4EAA4E;IACtE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAU9D"}

package/dist/global/store.js

@@ -1,5 +1,6 @@
-import { readFile, readdir } from "node:fs/promises";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { REGISTRY_FILE, parseRegistry, renderRegistry } from "./registry.js";
 /**
  * Resolve the global ghostrail config directory that holds account-level
  * settings and shared artifacts across all factory instances:
@@ -49,6 +50,29 @@ export class GlobalStore {
             return [];
         }
     }
+    registryPath() {
+        return join(this.dir, REGISTRY_FILE);
+    }
+    /**
+     * The registered ghostrails. `undefined` means the file exists but could not
+     * be trusted, which is deliberately different from `[]` (nothing registered
+     * yet): a caller must be able to tell "broken" from "empty" so it can say so.
+     */
+    async readRegistry() {
+        let raw;
+        try {
+            raw = await readFile(this.registryPath(), "utf8");
+        }
+        catch {
+            return [];
+        }
+        return parseRegistry(raw);
+    }
+    /** Write the registry, creating the global dir if this is the first entry. */
+    async writeRegistry(entries) {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(this.registryPath(), renderRegistry(entries), "utf8");
+    }
     /** An artifact's contents by name (with or without `.md`), or undefined. */
     async readArtifact(name) {
         for (const candidate of new Set([name, artifactFileName(name)])) {

package/dist/global/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/global/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAOjC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAc,EAAE,OAAe;IAC9D,IAAI,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,cAAc,CAAC;IACjG,MAAM,IAAI,GACR,GAAG,CAAC,eAAe,KAAK,SAAS,IAAI,GAAG,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC;QACjE,CAAC,CAAC,GAAG,CAAC,eAAe;QACrB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AACjC,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACL,GAAG,CAAS;IAE7B,YAAY,GAAW;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IACzC,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,YAAY;QAChB,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,MAAM,CAAC,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,aAAa;QACjB,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,KAAK,MAAM,SAAS,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;YACxE,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/global/store.ts"],"names":[],"mappings":"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"}

package/dist/service/index.d.ts

@@ -0,0 +1,3 @@
+export { type InstallOutcome, type ManagerKind, type ServiceManager, detectManager, disableAndStop, enableAndStart, installUnit, reload, removeUnit, systemdManager, systemdUnitDir, unitStates, } from "./manager.js";
+export { type UnitSpec, DASHBOARD_UNIT, renderDashboardUnit, parseUnitStates, renderSystemdUnit, stopTimeoutSeconds, unitName, } from "./unit.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/service/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,aAAa,EACb,cAAc,EACd,cAAc,EACd,WAAW,EACX,MAAM,EACN,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,QAAQ,EACb,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,GACT,MAAM,WAAW,CAAC"}

package/dist/service/index.js

@@ -0,0 +1,3 @@
+export { detectManager, disableAndStop, enableAndStart, installUnit, reload, removeUnit, systemdManager, systemdUnitDir, unitStates, } from "./manager.js";
+export { DASHBOARD_UNIT, renderDashboardUnit, parseUnitStates, renderSystemdUnit, stopTimeoutSeconds, unitName, } from "./unit.js";
+//# sourceMappingURL=index.js.map

package/dist/service/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,aAAa,EACb,cAAc,EACd,cAAc,EACd,WAAW,EACX,MAAM,EACN,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,GACT,MAAM,WAAW,CAAC"}