lastlight-shared 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Last Light Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Config types the workflow loader needs, lifted out of `lastlight-core`'s
+ * `config/config.ts` so `shared` never depends back on core (locked decision
+ * 11). Core re-exports these from `lastlight-shared` so its own
+ * `config/config.js` import surface is unchanged.
+ */
+export interface DisabledConfig {
+    workflows: string[];
+    crons: string[];
+    prompts: string[];
+    skills: string[];
+    agentContext: string[];
+}
+export interface RouteConfig {
+    github: Record<string, string>;
+    slack: Record<string, string>;
+}

package/dist/config-types.js

@@ -0,0 +1,8 @@
+/**
+ * Config types the workflow loader needs, lifted out of `lastlight-core`'s
+ * `config/config.ts` so `shared` never depends back on core (locked decision
+ * 11). Core re-exports these from `lastlight-shared` so its own
+ * `config/config.js` import surface is unchanged.
+ */
+export {};
+//# sourceMappingURL=config-types.js.map

package/dist/config-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/core-pin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pick the *commit* SHA for tag `pin` from `git ls-remote … 'refs/tags/<pin>*'`
+ * output. Annotated tags emit two rows — the tag object (`refs/tags/<pin>`) and
+ * the peeled commit (`refs/tags/<pin>^{}`); only the glob pattern surfaces the
+ * peeled row (an exact `refs/tags/<pin>` hides it). We want the commit, since
+ * that's what `git checkout <pin>` lands HEAD on and what an image built at the
+ * tag is stamped with. Preference: peeled commit → exact tag ref (lightweight
+ * tag / branch) → first row. Null when nothing looks like a SHA.
+ */
+export declare function pickTagCommit(lsRemoteOut: string | null, pin: string): string | null;
+/**
+ * The core-version pin for the overlay at `overlayDir`, or `null` to track main.
+ * `LASTLIGHT_CORE_VERSION` wins over the file. Missing / unreadable / malformed
+ * config.yaml is treated as unpinned (never throws).
+ */
+export declare function readCorePin(overlayDir: string): string | null;

package/dist/core-pin.js

@@ -0,0 +1,85 @@
+/**
+ * Read the core-version pin an overlay declares.
+ *
+ * The overlay's `config.yaml` may carry a `deploy.version` — a git tag/ref
+ * (e.g. `v0.10.6`) that pins which core version this instance runs. When set,
+ * `lastlight server update|setup` checks the core repo out at that ref instead
+ * of tracking `main`, and the dashboard drift banner compares the running image
+ * to the pinned tag rather than to `main` HEAD.
+ *
+ * This reader is deliberately standalone (a raw YAML read, not the full
+ * default/overlay/env config machinery) because its two callers run in very
+ * different contexts against a raw overlay checkout path:
+ *   - the host-local `lastlight server` CLI (no harness / runtime config) —
+ *     against `<serverHome>/instance`;
+ *   - the in-container harness banner (`src/admin/version.ts`) — against the
+ *     mounted `LASTLIGHT_OVERLAY_DIR` (`/app/instance`).
+ *
+ * `LASTLIGHT_CORE_VERSION` (env) overrides the file so CI can pin without
+ * editing config.yaml. Unset, or the sentinels `main` / `latest`, mean "track
+ * main" and return `null`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/** Normalize a raw pin value: trim, treat empty / `main` / `latest` as null. */
+function normalizePin(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const v = raw.trim();
+    if (!v)
+        return null;
+    const lower = v.toLowerCase();
+    if (lower === "main" || lower === "latest")
+        return null;
+    return v;
+}
+/**
+ * Pick the *commit* SHA for tag `pin` from `git ls-remote … 'refs/tags/<pin>*'`
+ * output. Annotated tags emit two rows — the tag object (`refs/tags/<pin>`) and
+ * the peeled commit (`refs/tags/<pin>^{}`); only the glob pattern surfaces the
+ * peeled row (an exact `refs/tags/<pin>` hides it). We want the commit, since
+ * that's what `git checkout <pin>` lands HEAD on and what an image built at the
+ * tag is stamped with. Preference: peeled commit → exact tag ref (lightweight
+ * tag / branch) → first row. Null when nothing looks like a SHA.
+ */
+export function pickTagCommit(lsRemoteOut, pin) {
+    if (!lsRemoteOut)
+        return null;
+    const rows = lsRemoteOut
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        const [sha, ref] = l.split(/\s+/);
+        return { sha: sha ?? "", ref: ref ?? "" };
+    });
+    const peeled = rows.find((r) => r.ref === `refs/tags/${pin}^{}`);
+    const exact = rows.find((r) => r.ref === `refs/tags/${pin}`);
+    const chosen = (peeled ?? exact ?? rows[0])?.sha ?? "";
+    return /^[0-9a-f]{7,40}$/i.test(chosen) ? chosen : null;
+}
+/**
+ * The core-version pin for the overlay at `overlayDir`, or `null` to track main.
+ * `LASTLIGHT_CORE_VERSION` wins over the file. Missing / unreadable / malformed
+ * config.yaml is treated as unpinned (never throws).
+ */
+export function readCorePin(overlayDir) {
+    const fromEnv = normalizePin(process.env.LASTLIGHT_CORE_VERSION);
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const parsed = parseYaml(readFileSync(join(overlayDir, "config.yaml"), "utf8"));
+        if (parsed && typeof parsed === "object") {
+            const deploy = parsed.deploy;
+            if (deploy && typeof deploy === "object") {
+                return normalizePin(deploy.version);
+            }
+        }
+    }
+    catch {
+        /* no overlay / no config.yaml / parse error → track main */
+    }
+    return null;
+}
+//# sourceMappingURL=core-pin.js.map

package/dist/core-pin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-pin.js","sourceRoot":"","sources":["../src/core-pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,gFAAgF;AAChF,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9B,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,WAA0B,EAAE,GAAW;IACnE,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,IAAI,GAAG,WAAW;SACrB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;IACL,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,aAAa,GAAG,KAAK,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,aAAa,GAAG,EAAE,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC;IACvD,OAAO,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IACjE,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAChF,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzC,MAAM,MAAM,GAAI,MAAkC,CAAC,MAAM,CAAC;YAC1D,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACzC,OAAO,YAAY,CAAE,MAAkC,CAAC,OAAO,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `lastlight-shared` — the light modules shared by the published `lastlight`
+ * CLI and `lastlight-core`. Node built-ins + `yaml` / `@clack/prompts` /
+ * `chalk` / `@earendil-works/pi-ai` (oauth subpath) / `lastlight-workflow-engine`
+ * (workflow schema) only — no heavy runtime deps (better-sqlite3, slack,
+ * octokit, hono, otel, agentic-pi) are ever reachable from here (fence F4).
+ *
+ * Invariant: no edge from `shared` back to `lastlight-core`.
+ *
+ * `./oauth` and `./workflow-loader` are also exposed as dedicated subpaths so
+ * core can keep thin re-export shims at their original file paths (preserving
+ * `vi.mock` targets + module-singleton identity) without leaking the whole
+ * barrel through those paths.
+ */
+export * from "./providers.js";
+export * from "./oauth.js";
+export * from "./overlay-bootstrap.js";
+export * from "./overlay-assets.js";
+export * from "./core-pin.js";
+export * from "./workflow-loader.js";
+export * from "./config-types.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * `lastlight-shared` — the light modules shared by the published `lastlight`
+ * CLI and `lastlight-core`. Node built-ins + `yaml` / `@clack/prompts` /
+ * `chalk` / `@earendil-works/pi-ai` (oauth subpath) / `lastlight-workflow-engine`
+ * (workflow schema) only — no heavy runtime deps (better-sqlite3, slack,
+ * octokit, hono, otel, agentic-pi) are ever reachable from here (fence F4).
+ *
+ * Invariant: no edge from `shared` back to `lastlight-core`.
+ *
+ * `./oauth` and `./workflow-loader` are also exposed as dedicated subpaths so
+ * core can keep thin re-export shims at their original file paths (preserving
+ * `vi.mock` targets + module-singleton identity) without leaking the whole
+ * barrel through those paths.
+ */
+export * from "./providers.js";
+export * from "./oauth.js";
+export * from "./overlay-bootstrap.js";
+export * from "./overlay-assets.js";
+export * from "./core-pin.js";
+export * from "./workflow-loader.js";
+export * from "./config-types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC"}

package/dist/oauth.d.ts

@@ -0,0 +1,43 @@
+import { getOAuthProvider, getOAuthProviders, type OAuthCredentials } from "@earendil-works/pi-ai/oauth";
+/** Stored form — pi-ai's CLI tags each entry with `type: "oauth"`; we match it. */
+export type StoredCredentials = OAuthCredentials & {
+    type?: string;
+};
+export type AuthMap = Record<string, StoredCredentials>;
+/** OAuth providers that CANNOT fall back to an API key — login is mandatory. */
+export declare const OAUTH_ONLY_PROVIDERS: ReadonlySet<string>;
+/** OAuth provider id backing a model spec, or undefined if it's API-key based. */
+export declare function oauthProviderIdForModel(spec: string): string | undefined;
+/**
+ * The env var pi-ai reads inside a sandbox for a provider's OAuth token, when
+ * one exists. Returns undefined for providers with no env-var route (Codex),
+ * which therefore cannot authenticate in the agentic-pi sandbox.
+ */
+export declare function oauthEnvVarForProvider(id: string): string | undefined;
+/**
+ * Resolve the credential-store path. Precedence:
+ *   1. explicit argument (a caller-computed path),
+ *   2. `LASTLIGHT_AUTH_FILE` (hard override),
+ *   3. `<stateDir | $STATE_DIR | ./data>/auth.json`.
+ * The CLI writes here and the harness reads here, so both must agree; passing
+ * the harness's resolved `stateDir` keeps them aligned even if the process cwd
+ * differs.
+ */
+export declare function resolveAuthFile(explicit?: string, stateDir?: string): string;
+export declare function loadAuthMap(file?: string, stateDir?: string): AuthMap;
+export declare function saveAuthMap(map: AuthMap, file?: string, stateDir?: string): void;
+export declare function hasOAuthCredentials(id: string, file?: string, stateDir?: string): boolean;
+export interface OAuthKeyResult {
+    apiKey: string;
+    credentials: OAuthCredentials;
+}
+/**
+ * Resolve a usable API key for an OAuth provider from stored credentials,
+ * refreshing an expired token and persisting the rotated credentials back to
+ * the store. Returns null when nothing is stored for `id`. Throws only if a
+ * refresh actually fails (expired refresh token, revoked grant) — callers
+ * should surface that as "re-run login".
+ */
+export declare function resolveOAuthApiKey(id: string, file?: string, stateDir?: string): Promise<OAuthKeyResult | null>;
+/** Re-exported so callers depend on this module, not pi-ai's oauth entry directly. */
+export { getOAuthProvider, getOAuthProviders };

package/dist/oauth.js

@@ -0,0 +1,103 @@
+/**
+ * OAuth credential management for LLM providers that authenticate with a
+ * subscription login instead of a static API key — ChatGPT Plus/Pro (Codex),
+ * Claude Pro/Max, and GitHub Copilot.
+ *
+ * pi-ai (`@earendil-works/pi-ai/oauth`) owns the actual OAuth flows, token
+ * refresh, and credential→apiKey conversion; this module is the thin Last
+ * Light layer on top:
+ *   - a single on-disk credential store (`auth.json`, same JSON shape pi-ai's
+ *     own CLI writes) resolved under `$STATE_DIR` so the CLI (writer) and the
+ *     running harness (reader) agree on one path,
+ *   - `resolveOAuthApiKey()` — refresh-if-expired + persist rotated creds +
+ *     return a usable key, used by the in-process chat path,
+ *   - the model-prefix → provider-id map and the sandbox env-var route so the
+ *     chat and sandbox executors can both find the right credential.
+ *
+ * Two consumption seams with different reach:
+ *   - **chat** (in-process pi-ai) — passes `apiKey` in the stream options, so
+ *     ALL three OAuth providers work, Codex included.
+ *   - **sandbox** (agentic-pi) — has no apiKey option; it reads provider creds
+ *     from env only. pi-ai honours `ANTHROPIC_OAUTH_TOKEN` and
+ *     `COPILOT_GITHUB_TOKEN`, but Codex (chatgpt.com backend) has no env route,
+ *     so a Codex model cannot run in the sandbox. See `oauthEnvVarForProvider`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { getOAuthApiKey, getOAuthProvider, getOAuthProviders, } from "@earendil-works/pi-ai/oauth";
+import { OAUTH_PROVIDERS, oauthProviderByModelPrefix, oauthProviderById } from "./providers.js";
+/** OAuth providers that CANNOT fall back to an API key — login is mandatory. */
+export const OAUTH_ONLY_PROVIDERS = new Set(OAUTH_PROVIDERS.filter((p) => p.oauthOnly).map((p) => p.id));
+/** OAuth provider id backing a model spec, or undefined if it's API-key based. */
+export function oauthProviderIdForModel(spec) {
+    const prefix = spec.includes("/") ? spec.slice(0, spec.indexOf("/")) : spec;
+    return oauthProviderByModelPrefix(prefix)?.id;
+}
+/**
+ * The env var pi-ai reads inside a sandbox for a provider's OAuth token, when
+ * one exists. Returns undefined for providers with no env-var route (Codex),
+ * which therefore cannot authenticate in the agentic-pi sandbox.
+ */
+export function oauthEnvVarForProvider(id) {
+    return oauthProviderById(id)?.sandboxEnvVar ?? undefined;
+}
+/**
+ * Resolve the credential-store path. Precedence:
+ *   1. explicit argument (a caller-computed path),
+ *   2. `LASTLIGHT_AUTH_FILE` (hard override),
+ *   3. `<stateDir | $STATE_DIR | ./data>/auth.json`.
+ * The CLI writes here and the harness reads here, so both must agree; passing
+ * the harness's resolved `stateDir` keeps them aligned even if the process cwd
+ * differs.
+ */
+export function resolveAuthFile(explicit, stateDir) {
+    if (explicit)
+        return resolve(explicit);
+    if (process.env.LASTLIGHT_AUTH_FILE)
+        return resolve(process.env.LASTLIGHT_AUTH_FILE);
+    return resolve(stateDir || process.env.STATE_DIR || "data", "auth.json");
+}
+export function loadAuthMap(file, stateDir) {
+    const path = resolveAuthFile(file, stateDir);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveAuthMap(map, file, stateDir) {
+    const path = resolveAuthFile(file, stateDir);
+    mkdirSync(dirname(path), { recursive: true });
+    // Mode 0600 — the file holds long-lived refresh tokens.
+    writeFileSync(path, JSON.stringify(map, null, 2), { mode: 0o600 });
+}
+export function hasOAuthCredentials(id, file, stateDir) {
+    return !!loadAuthMap(file, stateDir)[id];
+}
+/**
+ * Resolve a usable API key for an OAuth provider from stored credentials,
+ * refreshing an expired token and persisting the rotated credentials back to
+ * the store. Returns null when nothing is stored for `id`. Throws only if a
+ * refresh actually fails (expired refresh token, revoked grant) — callers
+ * should surface that as "re-run login".
+ */
+export async function resolveOAuthApiKey(id, file, stateDir) {
+    const map = loadAuthMap(file, stateDir);
+    if (!map[id])
+        return null;
+    const res = await getOAuthApiKey(id, map);
+    if (!res)
+        return null;
+    // Persist the rotated credentials so the next refresh chains from the new
+    // token rather than re-using a spent one.
+    map[id] = { type: "oauth", ...res.newCredentials };
+    saveAuthMap(map, file, stateDir);
+    return { apiKey: res.apiKey, credentials: res.newCredentials };
+}
+/** Re-exported so callers depend on this module, not pi-ai's oauth entry directly. */
+export { getOAuthProvider, getOAuthProviders };
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

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

package/dist/overlay-assets.d.ts

@@ -0,0 +1,20 @@
+export type OverlayAssetType = "workflow" | "cron" | "prompt" | "skill" | "agent-context";
+export interface OverlayAsset {
+    type: OverlayAssetType;
+    /** Logical name — workflow/cron/skill name, or the filename for prompts/context. */
+    name: string;
+    /** True when a same-named built-in exists under `coreRoot` (overlay shadows it);
+     *  false when the overlay adds something the built-ins don't have. */
+    shadowsDefault: boolean;
+}
+export interface EnumerateOpts {
+    /** Built-in asset tree (the lastlight checkout root). */
+    coreRoot?: string;
+    /** Overlay asset tree (the instance/ overlay root). */
+    overlayRoot?: string;
+}
+/**
+ * List every asset the overlay provides, tagging each as shadowing a built-in or
+ * a fresh addition. Returns `[]` when no overlay is configured or present.
+ */
+export declare function enumerateOverlayAssets(opts: EnumerateOpts): OverlayAsset[];

package/dist/overlay-assets.js

@@ -0,0 +1,114 @@
+/**
+ * Enumerate the assets a deployment overlay overrides or adds.
+ *
+ * The instance overlay (`$LASTLIGHT_OVERLAY_DIR`, prod `instance/`) can replace
+ * or add workflows, prompts, skills, and agent-context files by logical name —
+ * the layer-aware resolution lives in `src/workflows/loader.ts`. This module is
+ * the read-only inverse: given the built-in (`coreRoot`) and overlay
+ * (`overlayRoot`) trees, list every asset the overlay provides and whether it
+ * **shadows** a same-named built-in or is a fresh **addition**.
+ *
+ * It's a pure filesystem walk (no loader caches), so the host-local CLI
+ * (`lastlight server status`, `lastlight fork`) and the in-harness admin API
+ * (`GET /admin/api/overrides`) can share one source of truth.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function listFiles(dir, predicate) {
+    if (!isDir(dir))
+        return [];
+    return readdirSync(dir).filter(predicate).sort();
+}
+function listDirs(dir) {
+    if (!isDir(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => isDir(join(dir, n)))
+        .sort();
+}
+const isYaml = (n) => n.endsWith(".yaml") || n.endsWith(".yml");
+const isMarkdown = (n) => n.endsWith(".md");
+/** Read a workflow YAML's `name`/`kind` without throwing on malformed files. */
+function readWorkflowMeta(filePath) {
+    try {
+        const raw = parseYaml(readFileSync(filePath, "utf-8"));
+        if (!raw || typeof raw.name !== "string")
+            return null;
+        return { name: raw.name, kind: typeof raw.kind === "string" ? raw.kind : "" };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Index built-in assets by logical name so overlay entries can be tagged as
+ * shadowing vs adding. Workflows/crons are keyed by their YAML `name`; prompts,
+ * skills, and agent-context by filename / directory name.
+ */
+function indexBuiltins(coreRoot) {
+    const workflows = new Set();
+    const crons = new Set();
+    const workflowDir = join(coreRoot, "workflows");
+    for (const file of listFiles(workflowDir, isYaml)) {
+        const meta = readWorkflowMeta(join(workflowDir, file));
+        if (!meta)
+            continue;
+        (meta.kind === "cron" ? crons : workflows).add(meta.name);
+    }
+    return {
+        workflows,
+        crons,
+        prompts: new Set(listFiles(join(coreRoot, "workflows", "prompts"), isMarkdown)),
+        skills: new Set(listDirs(join(coreRoot, "skills"))),
+        agentContext: new Set(listFiles(join(coreRoot, "agent-context"), isMarkdown)),
+    };
+}
+/**
+ * List every asset the overlay provides, tagging each as shadowing a built-in or
+ * a fresh addition. Returns `[]` when no overlay is configured or present.
+ */
+export function enumerateOverlayAssets(opts) {
+    const { coreRoot, overlayRoot } = opts;
+    if (!overlayRoot || !isDir(overlayRoot))
+        return [];
+    const builtins = coreRoot && isDir(coreRoot)
+        ? indexBuiltins(coreRoot)
+        : { workflows: new Set(), crons: new Set(), prompts: new Set(), skills: new Set(), agentContext: new Set() };
+    const assets = [];
+    // Workflows + crons — keyed by YAML `name`, split by `kind`.
+    const overlayWorkflowDir = join(overlayRoot, "workflows");
+    for (const file of listFiles(overlayWorkflowDir, isYaml)) {
+        const meta = readWorkflowMeta(join(overlayWorkflowDir, file));
+        if (!meta)
+            continue;
+        const isCron = meta.kind === "cron";
+        assets.push({
+            type: isCron ? "cron" : "workflow",
+            name: meta.name,
+            shadowsDefault: (isCron ? builtins.crons : builtins.workflows).has(meta.name),
+        });
+    }
+    // Prompts — keyed by filename under workflows/prompts/.
+    for (const file of listFiles(join(overlayRoot, "workflows", "prompts"), isMarkdown)) {
+        assets.push({ type: "prompt", name: file, shadowsDefault: builtins.prompts.has(file) });
+    }
+    // Skills — keyed by directory name under skills/.
+    for (const dir of listDirs(join(overlayRoot, "skills"))) {
+        assets.push({ type: "skill", name: dir, shadowsDefault: builtins.skills.has(dir) });
+    }
+    // Agent-context — keyed by filename under agent-context/.
+    for (const file of listFiles(join(overlayRoot, "agent-context"), isMarkdown)) {
+        assets.push({ type: "agent-context", name: file, shadowsDefault: builtins.agentContext.has(file) });
+    }
+    return assets;
+}
+//# sourceMappingURL=overlay-assets.js.map

package/dist/overlay-assets.js.map

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

package/dist/overlay-bootstrap.d.ts

@@ -0,0 +1,44 @@
+/** `.gitignore` for the overlay so it can be its own private repo without
+ *  leaking secrets. Everything under `secrets/` is ignored except the template. */
+export declare const OVERLAY_GITIGNORE: string;
+/** Placeholder `config.yaml` for a fresh overlay (no managed repos yet). */
+export declare const OVERLAY_CONFIG_PLACEHOLDER: string;
+/** Template `secrets/.env.example` — the only tracked file under `secrets/`.
+ *  Mirrors the keys `npx lastlight setup` writes into `secrets/.env`. */
+export declare const OVERLAY_ENV_EXAMPLE: string;
+/** README dropped into a freshly scaffolded overlay. */
+export declare const OVERLAY_README: string;
+export interface GhStatus {
+    /** `gh` is on PATH. */
+    installed: boolean;
+    /** `gh auth status` succeeded — we can create repos. */
+    authed: boolean;
+    /** Authenticated GitHub login, when resolvable. */
+    login?: string;
+}
+/** Probe the GitHub CLI. Never throws — a missing/unauthed `gh` resolves to a
+ *  status the callers fall back from (print manual commands instead). */
+export declare function detectGh(): Promise<GhStatus>;
+export interface ScaffoldResult {
+    /** Repo-relative paths of files this call created (existing files untouched). */
+    created: string[];
+}
+/**
+ * Write the default overlay files into `instanceDir`, creating only what's
+ * missing — never overwriting an existing file. Returns the relative paths
+ * created so callers can report them.
+ */
+export declare function scaffoldOverlayFiles(instanceDir: string): ScaffoldResult;
+export interface BootstrapOpts {
+    /** Pre-probed gh status (call {@link detectGh} once and pass it in). */
+    gh: GhStatus;
+    /** Non-interactive — skip prompts, just print the manual commands. */
+    yes?: boolean;
+}
+/**
+ * Version `instanceDir` as a private git repo and (optionally) create + push a
+ * GitHub repo for it. Idempotent: skips `git init` when already a repo, and
+ * skips repo creation when an `origin` remote already exists. Falls back to
+ * printing the manual commands whenever `gh` is unavailable or the user declines.
+ */
+export declare function bootstrapOverlayRepo(instanceDir: string, opts: BootstrapOpts): Promise<void>;