lastlight-shared 0.1.6 → 0.2.0

package/dist/index.d.ts

@@ -19,3 +19,4 @@ export * from "./overlay-assets.js";
 export * from "./core-pin.js";
 export * from "./workflow-loader.js";
 export * from "./config-types.js";
+export * from "./repo-config-schema.js";

package/dist/index.js

@@ -19,4 +19,5 @@ export * from "./overlay-assets.js";
 export * from "./core-pin.js";
 export * from "./workflow-loader.js";
 export * from "./config-types.js";
+export * from "./repo-config-schema.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"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;AAClC,cAAc,yBAAyB,CAAC"}

package/dist/repo-config-schema.d.ts

@@ -0,0 +1,308 @@
+/**
+ * The PURE half of the per-repository config layer (issue #180) — the schema,
+ * the operator bounds, and the validators/merger that enforce them.
+ *
+ * A managed repo may commit a `.lastlight/` directory that overrides a BOUNDED
+ * subset of Last Light's config for runs against that repo. The directory
+ * mirrors a deployment overlay's on-disk shape exactly:
+ *
+ *   .lastlight/
+ *     lastlight.yml                  # the config override
+ *     workflows/prompts/*.md         # prompt overrides
+ *     skills/<name>/SKILL.md         # skill overrides
+ *     agent-context/*.md             # persona/rules additions
+ *
+ * ── Why this lives in `lastlight-shared` ──────────────────────────────────
+ * Two consumers need exactly the same answers about a `.lastlight/` tree:
+ *   - `lastlight-core` at runtime, after fetching the layer from GitHub
+ *     (`apps/server/src/config/repo-config.ts`, which owns the impure half —
+ *     the fetch, the TTL cache, the on-disk unpack — and re-exports everything
+ *     here so its import surface is unchanged); and
+ *   - the `lastlight` CLI, offline, inside a user's own code repo
+ *     (`lastlight repo config validate`).
+ * The CLI must never gain a dependency edge to core, so the bounds logic sits
+ * here — the one package both already depend on. Nothing in this file touches
+ * the filesystem, the network, or runtime config: it is a function of its
+ * arguments, which is also what makes it directly unit-testable.
+ *
+ * ── The trust rule ────────────────────────────────────────────────────────
+ * The layer is ALWAYS read from the repo's **default branch**. Never a PR head.
+ * Never the sandbox checkout. That rule is enforced by the fetcher in core;
+ * this module only describes what may appear in the layer once it arrives.
+ *
+ * ── The failure rule ──────────────────────────────────────────────────────
+ * Warn, drop the bad bits, run anyway. A repo's config file must never fail a
+ * run. Invalid YAML drops the whole file; an unknown or out-of-bounds key drops
+ * just that key. Every rejection becomes a structured {@link RepoConfigWarning}
+ * so the dashboard/CLI can report it back to the repo's owners.
+ */
+import type { DisabledConfig } from "./config-types.js";
+/** Hard cap on the unpacked `.lastlight/` layer, in bytes. */
+export declare const REPO_CONFIG_MAX_BYTES: number;
+/** Hard cap on the number of files in the unpacked layer. */
+export declare const REPO_CONFIG_MAX_FILES = 200;
+/** The config file inside `.lastlight/`. Exactly this name — no `.yaml` variant. */
+export declare const REPO_CONFIG_FILE = "lastlight.yml";
+/**
+ * The operator's bounds on the per-repo config layer (issue #180). A repo may
+ * narrow its own behaviour within these bounds; it can never widen them, and
+ * violating them drops the offending key with a warning rather than failing
+ * the run.
+ *
+ * Trust note: the layer this policy bounds is always fetched from the repo's
+ * DEFAULT BRANCH. A PR head can't reach it, so a PR can't reconfigure the agent
+ * that reviews it. That rule lives in `apps/server/src/config/repo-config.ts`;
+ * this type only describes the bounds.
+ */
+export interface RepoConfigPolicy {
+    /** Master switch. `false` ignores every repo's `.lastlight/` entirely (no fetch). */
+    enabled: boolean;
+    /**
+     * Config keys a repo may set, as dotted paths (`models`, `disabled.workflows`,
+     * …). A repo leaf is kept when some entry is that leaf's path or a prefix of
+     * it — so `models` admits `models.architect`, while `disabled.workflows` does
+     * NOT admit `disabled.prompts`. Everything else is dropped with a warning.
+     */
+    allowKeys: string[];
+    /**
+     * Model specs a repo may select. `null` (the default) means "any model whose
+     * `provider/` prefix is a provider Last Light knows how to wire" — the repo
+     * still can't invent a provider. A list restricts to exactly those specs.
+     */
+    allowedModels: string[] | null;
+    /**
+     * Whether the repo's asset overrides (`workflows/prompts/*.md`,
+     * `skills/<name>/SKILL.md`, `agent-context/*.md`) are unpacked and used.
+     * `false` keeps `lastlight.yml` only.
+     */
+    allowAssets: boolean;
+}
+/**
+ * The allow-list a deployment gets when it says nothing. Kept as a constant so
+ * the normaliser, the docs, `config/default.yaml` and the CLI's offline
+ * validator can't drift apart.
+ *
+ * It MUST stay identical to `repoConfig.allowKeys` in
+ * `apps/server/config/default.yaml`: this list is what a deployment falls back
+ * to when config isn't in reach (`repoConfigPolicy()`'s no-config path, and the
+ * CLI's offline `lastlight repo config validate`), so a divergence tells repo
+ * owners their file is out of bounds when it isn't. Pinned by the
+ * `default allow-list` block in `apps/server/tests/config/repo-config-shared.test.ts`
+ * — the two drifted apart once already, silently.
+ */
+export declare const DEFAULT_REPO_CONFIG_ALLOW_KEYS: readonly string[];
+/**
+ * The bounds to assume when no deployment config is in reach — the shipped
+ * defaults. The offline CLI validator (`lastlight repo config validate`) uses
+ * this: it can't know the operator's narrowing, so it validates against the
+ * widest shipped policy and says so.
+ */
+export declare function defaultRepoConfigPolicy(): RepoConfigPolicy;
+/** Which config layer supplied a resolved leaf. Mirrors core's `ConfigSource`. */
+export type ConfigSource = "default" | "overlay" | "env" | "repo";
+/** Why a piece of a repo's `.lastlight/` was dropped. */
+export type RepoConfigWarningCode = 
+/** `lastlight.yml` did not parse as YAML — the whole file is ignored. */
+"invalid-yaml"
+/** `lastlight.yml` parsed to something that isn't a mapping. */
+ | "not-a-mapping"
+/** The key isn't in the operator's `repoConfig.allowKeys`. */
+ | "key-not-allowed"
+/** The key is allowed but the value has the wrong type/shape. */
+ | "invalid-value"
+/** A model spec outside `repoConfig.allowedModels`. */
+ | "model-not-allowed"
+/** A model spec whose `provider/` prefix isn't a provider we can wire. */
+ | "unknown-provider"
+/** An `approval` entry that would clear a gate — the layer is add-only. */
+ | "approval-downgrade"
+/** A file path that escapes the layer root. */
+ | "path-escape"
+/** A symlink (or other non-regular blob) in the layer. */
+ | "symlink"
+/** The layer exceeded {@link REPO_CONFIG_MAX_BYTES}. */
+ | "size-cap"
+/** The layer exceeded {@link REPO_CONFIG_MAX_FILES}. */
+ | "file-count-cap"
+/** A workflow YAML under `workflows/` — repos may contribute prompts, not workflows. */
+ | "workflow-not-allowed"
+/** Asset files present but `repoConfig.allowAssets` is false. */
+ | "assets-not-allowed"
+/** Files in a layer directory that don't match its expected shape. */
+ | "unrecognised-asset"
+/** The GitHub fetch failed; the previous cached layer (if any) still stands. */
+ | "fetch-failed";
+/**
+ * One structured, reportable rejection. Deliberately a plain data object (not
+ * an Error): these are collected, persisted in the cache sidecar and rendered
+ * by the dashboard/CLI, never thrown.
+ */
+export interface RepoConfigWarning {
+    code: RepoConfigWarningCode;
+    /** `owner/repo` this warning belongs to, when known. */
+    repo?: string;
+    /** The config path (`models.architect`) or file path (`workflows/x.yaml`) at fault. */
+    path: string;
+    /** One-line human-readable explanation, safe to post back to the repo. */
+    message: string;
+}
+/**
+ * One blob of a `.lastlight/` tree, as handed to {@link sanitizeRepoFiles}.
+ * Structurally the same shape core's GitHub client produces (`RepoConfigFile`
+ * in `apps/server/src/engine/github/github.ts`) and the CLI reads off disk —
+ * declared here so the bounds logic needs no GitHub types.
+ */
+export interface RepoLayerFile {
+    /** Path relative to `.lastlight/`. */
+    path: string;
+    /** Git filemode (`100644`, `100755`, `120000`, …). */
+    mode: string;
+    size: number;
+    content: Buffer;
+}
+/** A repo's fetched-and-unpacked `.lastlight/` layer. */
+export interface RepoLayer {
+    /** `owner/repo`. */
+    repo: string;
+    /** The ref this layer was read from — always the repo's default branch. */
+    defaultBranch: string;
+    /** Git tree SHA of `.lastlight/` — the content identity used for conditional refetch. */
+    treeSha: string;
+    /** ETag of the default branch's root tree, for the cheap 304 path. */
+    etag?: string;
+    /** ISO timestamp of the last successful download (not of the last check). */
+    fetchedAt: string;
+    /**
+     * Absolute path of the unpacked tree. Mirrors an overlay root
+     * (`workflows/`, `skills/`, `agent-context/`), so it can be handed to the
+     * layer-aware asset loader directly.
+     */
+    root: string;
+    /** Parsed `lastlight.yml` — raw and UNVALIDATED; bounds are applied at resolve time. */
+    config?: Record<string, unknown>;
+    /** Accepted asset paths relative to {@link root}. Empty when `allowAssets` is false. */
+    assets: string[];
+    /** Everything dropped while fetching/unpacking this layer. */
+    warnings: RepoConfigWarning[];
+}
+/**
+ * The boot-resolved config the repo layer is applied on top of: the merged
+ * (default→overlay→env) values plus the matching provenance tree from
+ * `resolveConfigLayers`. Core builds one with `repoConfigBaseFromRuntime`.
+ */
+export interface RepoConfigBase {
+    value: Record<string, unknown>;
+    sources: Record<string, unknown>;
+}
+/** The effective, repo-specific values for the keys a repo is allowed to touch. */
+export interface RepoMergedConfig {
+    models: Record<string, string>;
+    variants: Record<string, string>;
+    /**
+     * Full disabled shape. Only `workflows` and `crons` are repo-settable by
+     * default; the rest always come from the operator's layers.
+     */
+    disabled: DisabledConfig;
+    approval: Record<string, boolean>;
+}
+/** Provenance mirror of {@link RepoMergedConfig} — each leaf tagged with its winning layer. */
+export interface RepoConfigSources {
+    models: Record<string, ConfigSource>;
+    variants: Record<string, ConfigSource>;
+    disabled: Record<keyof DisabledConfig, ConfigSource>;
+    approval: Record<string, ConfigSource>;
+}
+/** Result of {@link resolveRepoConfig}. */
+export interface ResolvedRepoConfig {
+    merged: RepoMergedConfig;
+    sources: RepoConfigSources;
+    /** Fetch/unpack warnings from the layer PLUS everything this resolve dropped. */
+    warnings: RepoConfigWarning[];
+}
+/** What role a path inside `.lastlight/` plays in the repo layer. */
+export type RepoLayerPathKind = "config" | "prompt" | "skill" | "agent-context";
+/**
+ * Classify a path relative to `.lastlight/`, or `null` when it is not part of
+ * the layer at all.
+ *
+ * `null` is a routine answer, not an error: `.lastlight/` is shared real
+ * estate. With `buildAssets.location: repo` the build workflow commits its
+ * handoff docs to `.lastlight/<issueKey>/*.md`, and repos are free to keep
+ * other things there. Those are simply outside the layer — the warning path is
+ * reserved for files that LOOK like layer assets but have the wrong shape
+ * (see {@link sanitizeRepoFiles}).
+ */
+export declare function repoLayerPathKind(path: string): RepoLayerPathKind | null;
+/** True when a path is a workflow DEFINITION — the one thing a repo may never contribute. */
+export declare function isRepoWorkflowPath(path: string): boolean;
+/**
+ * Apply every file-level bound to a `.lastlight/` subtree.
+ *
+ * Pure — takes the blobs, returns the ones that may be written to disk plus a
+ * warning per rejection. The caps are enforced here as well as at fetch time
+ * (the client stops downloading at its own limits) because this function is the
+ * last gate before anything touches the filesystem, and defence in depth is
+ * cheap.
+ *
+ * Generic in the file type so a caller carrying a richer blob shape (core's
+ * `RepoConfigFile`) gets its own type back rather than a widened one.
+ */
+export declare function sanitizeRepoFiles<T extends RepoLayerFile>(files: readonly T[], policy: RepoConfigPolicy, repo?: string): {
+    accepted: T[];
+    warnings: RepoConfigWarning[];
+};
+/**
+ * Parse a repo's `lastlight.yml`. Malformed YAML, or YAML that isn't a mapping,
+ * drops the WHOLE file — a half-understood config file is more dangerous than
+ * none, and the repo gets a warning either way.
+ */
+export declare function parseRepoConfigYaml(raw: string, repo?: string): {
+    config?: Record<string, unknown>;
+    warnings: RepoConfigWarning[];
+};
+/**
+ * Reduce a repo's raw `lastlight.yml` to the sub-tree it is actually allowed to
+ * contribute. Pure. Everything dropped produces a warning.
+ *
+ * `base` supplies the operator's current values, which the `approval` add-only
+ * rule needs: a repo may raise a gate, never lower one.
+ */
+export declare function sanitizeRepoConfigLayer(raw: Record<string, unknown> | undefined, policy: RepoConfigPolicy, base: RepoConfigBase, repo?: string): {
+    layer: Record<string, unknown>;
+    warnings: RepoConfigWarning[];
+};
+/**
+ * Apply a repo's layer on top of the boot config and report what happened.
+ *
+ * PURE — no fs, no network, no runtime-config reads. Plain objects deep-merge
+ * key-by-key while arrays and scalars replace wholesale — byte-for-byte the
+ * semantics of the boot layers (see {@link mergeLayer}), so the repo layer can
+ * never acquire semantics the operator's layers don't have.
+ *
+ * Note on `disabled.*`: those are arrays, so a repo's list REPLACES the
+ * operator's rather than adding to it (locked precedence). Operators who don't
+ * want that remove `disabled.workflows` / `disabled.crons` from
+ * `repoConfig.allowKeys`.
+ *
+ * Passing `undefined` for `repoLayer` (no `.lastlight/`, fetch failed, feature
+ * disabled) returns the base unchanged with no warnings — the inert path.
+ */
+export declare function resolveRepoConfig(base: RepoConfigBase, policy: RepoConfigPolicy, repoLayer?: RepoLayer): ResolvedRepoConfig;
+/**
+ * Merge one layer INTO `value`/`sources` in place, tagging every leaf it
+ * supplies with `source`.
+ *
+ * THE single definition of Last Light's config-merge semantics: plain objects
+ * deep-merge key-by-key so each leaf resolves (and is attributed) on its own;
+ * arrays and scalars replace wholesale. Core's boot-layer resolver
+ * (`apps/server/src/config/config-resolve.ts`) re-exports this rather than
+ * carrying its own — the repo layer must merge exactly the way default/overlay/
+ * env do, or a repo could acquire precedence the operator's own layers don't
+ * have, and two implementations is exactly how that drift starts.
+ *
+ * It lives HERE, in the leaf package, because the direction of the dependency
+ * edge only permits it here: `lastlight-shared` may never depend on core.
+ */
+export declare function mergeLayer(value: Record<string, unknown>, sources: Record<string, unknown>, layer: Record<string, unknown>, source: ConfigSource): void;
+/** Narrow an unknown provenance leaf to a {@link ConfigSource}. */
+export declare function isConfigSource(value: unknown): value is ConfigSource;