nikos 0.1.1 → 0.2.0

package/dist/commands/validate.js

@@ -1,19 +1,25 @@
 import Ajv2020Module from "ajv/dist/2020.js";
 const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse } from "yaml";
 import { lintFeature } from "../lint/gherkin.js";
 import { lintConstitution } from "../lint/constitution.js";
 import { BET_ID, CROSS_REF, planningDir } from "../lib/bets.js";
-import { featureStoryIds, featureTag, findIntentDir, read, rel, walk } from "../lib/project.js";
+import { approvalLapse } from "../lib/approvals.js";
+import { store } from "../lib/store.js";
+import { approvalsDir, stateDir, storyFiles } from "../lib/state-files.js";
+import { featureStoryIds, featureTag, featureTags, findIntentDir, isDone, read, rel, specHash, walk } from "../lib/project.js";
 const here = dirname(fileURLToPath(import.meta.url));
 // Works from src/ (tests) and dist/ (published): schemas sit at the package root.
 const schemaDir = [join(here, "../../schemas"), join(here, "../schemas")].find((d) => existsSync(d));
 const ajv = new Ajv2020({ allErrors: true, strict: false });
-const checkStorymap = ajv.compile(JSON.parse(read(join(schemaDir, "storymap.schema.json"))));
-const checkState = ajv.compile(JSON.parse(read(join(schemaDir, "state.schema.json"))));
+// The schemas ship with nikOS, so they're read from disk whatever store is in use.
+const schemaFile = (name) => JSON.parse(readFileSync(join(schemaDir, name), "utf8"));
+const checkStorymap = ajv.compile(schemaFile("storymap.schema.json"));
+const checkState = ajv.compile(schemaFile("state.schema.json"));
+const checkApprovals = ajv.compile(schemaFile("approvals.schema.json"));
 function pointer(e) {
     return e.instancePath.replace(/^\//, "").split("/").filter(Boolean).join(".") || "(root)";
 }
@@ -42,7 +48,7 @@ function describe(e, data) {
 }
 function loadYaml(dir, name, issues) {
     const path = join(dir, name);
-    if (!existsSync(path)) {
+    if (!store().exists(path)) {
         issues.push({ file: name, message: "file is missing", hint: "run `nikos init` to create it" });
         return undefined;
     }
@@ -76,9 +82,15 @@ export function validate(start) {
     // Cross-file checks only when both files parsed into objects.
     const mapStories = new Map();
     const activityIds = new Set();
+    const personaIds = new Set();
     // Each step id names its activity; ids are unique across the map so a @step tag is enough.
     const stepActivity = new Map();
     if (storymap && typeof storymap === "object") {
+        for (const p of storymap.personas ?? []) {
+            if (personaIds.has(p?.id))
+                errors.push({ file: "storymap.yaml", message: `persona '${p.id}' appears more than once` });
+            personaIds.add(p?.id);
+        }
         for (const a of storymap.activities ?? []) {
             activityIds.add(a?.id);
             for (const st of a?.steps ?? []) {
@@ -107,13 +119,15 @@ export function validate(start) {
         }
     }
     const constitutionPath = join(dir, "constitution.md");
-    if (existsSync(constitutionPath)) {
+    if (store().exists(constitutionPath)) {
         for (const issue of lintConstitution(read(constitutionPath))) {
             (issue.level === "error" ? errors : warnings).push({ file: "constitution.md", message: issue.message, hint: issue.hint });
         }
     }
     // Features
     const featureIds = new Map();
+    const dependsOn = new Map();
+    const hashes = new Map();
     for (const path of walk(join(dir, "features"), ".feature")) {
         const file = rel(dir, path);
         const text = read(path);
@@ -148,32 +162,130 @@ export function validate(start) {
             else if (owner !== activity)
                 errors.push({ file, message: `@step-${step} belongs to activity '${owner}', not '${activity}'` });
         }
+        for (const persona of featureTags(text, "persona")) {
+            if (storymap && !personaIds.has(persona))
+                errors.push({ file, message: `@persona-${persona} is not a persona in storymap.yaml`, hint: "add it under personas:, or fix the tag" });
+        }
+        dependsOn.set(id, featureTags(text, "depends"));
+        hashes.set(id, specHash(text));
         const release = featureTag(text, "release");
         if (release && mapStories.has(id) && Number(release) !== mapStories.get(id)) {
             warnings.push({ file, message: `is tagged @release-${release} but storymap.yaml puts ${id} in release ${mapStories.get(id)}`, hint: `move it with nikos release move ${id} <n>, which keeps both in step` });
         }
     }
-    const stateStories = (state && typeof state === "object" && state.stories) || {};
-    if (storymap && state) {
+    const stateStories = { ...((state && typeof state === "object" && state.stories) || {}) };
+    // Where each story's state is: state.yaml, or its own file under state/.
+    const stateFile = (id) => (store().exists(join(stateDir(dir), `${id}.yaml`)) ? `state/${id}.yaml` : "state.yaml");
+    for (const f of storyFiles(stateDir(dir))) {
+        const file = `state/${f.id}.yaml`;
+        const entry = loadYaml(dir, file, errors);
+        if (entry === undefined)
+            continue;
+        if (!/^[A-Z][A-Z0-9]{0,9}-[0-9]+$/.test(f.id)) {
+            errors.push({ file, message: `'${f.id}' is not a story id`, hint: "name each file after its story, e.g. state/HT-1.yaml" });
+            continue;
+        }
+        if (f.id in stateStories)
+            errors.push({ file, message: `${f.id} is also in state.yaml`, hint: "keep one: nikos migrate per-story moves every story to its own file" });
+        const wrapped = { format_version: 1, stories: { [f.id]: entry } };
+        if (!checkState(wrapped))
+            for (const e of checkState.errors ?? [])
+                errors.push({ file, message: describe(e, wrapped).replace(`stories.${f.id}`, f.id) });
+        stateStories[f.id] = entry;
+    }
+    if (storymap && (state || Object.keys(stateStories).length)) {
         for (const id of mapStories.keys()) {
             if (!featureIds.has(id)) {
                 errors.push({ file: "storymap.yaml", message: `${id} has no feature file`, hint: `add intent/features/<activity>/<slug>.feature tagged @${id}` });
             }
             if (!(id in stateStories)) {
-                errors.push({ file: "state.yaml", message: `${id} is in storymap.yaml but has no entry under stories`, hint: `add "${id}: { status: todo }"` });
+                errors.push(store().isDir(stateDir(dir))
+                    ? { file: `state/${id}.yaml`, message: `${id} is in storymap.yaml but has no state file`, hint: `add intent/state/${id}.yaml with "status: todo"` }
+                    : { file: "state.yaml", message: `${id} is in storymap.yaml but has no entry under stories`, hint: `add "${id}: { status: todo }"` });
             }
         }
         for (const id of Object.keys(stateStories)) {
             if (!mapStories.has(id)) {
-                errors.push({ file: "state.yaml", message: `stories.${id} is an unknown story id`, hint: "add it to a release in storymap.yaml or remove it" });
+                errors.push({ file: stateFile(id), message: stateFile(id) === "state.yaml" ? `stories.${id} is an unknown story id` : `${id} is an unknown story id`, hint: "add it to a release in storymap.yaml or remove it" });
             }
         }
-        for (const id of state.run?.queue ?? []) {
+        for (const id of state?.run?.queue ?? []) {
             if (!mapStories.has(id))
                 errors.push({ file: "state.yaml", message: `run.queue has unknown story id ${id}` });
         }
+        for (const [id, entry] of Object.entries(stateStories)) {
+            if (!isDone(entry?.status) || !entry?.spec_hash || !hashes.has(id) || hashes.get(id) === entry.spec_hash)
+                continue;
+            warnings.push({
+                file: featureIds.get(id),
+                message: `${id} changed after it was ${entry.status}`,
+                hint: `if the change matters, move it back: nikos state set ${id} needs_rework`,
+            });
+        }
+    }
+    // Approvals are optional: approvals.yaml (or approvals/<ID>.yaml) appears with the first sign-off.
+    const signoffs = [];
+    if (store().exists(join(dir, "approvals.yaml"))) {
+        const approvals = loadYaml(dir, "approvals.yaml", errors);
+        if (approvals !== undefined && !checkApprovals(approvals)) {
+            for (const e of checkApprovals.errors ?? []) {
+                if (e.keyword === "pattern" && e.propertyName)
+                    continue;
+                errors.push({ file: "approvals.yaml", message: describe(e, approvals) });
+            }
+        }
+        else if (approvals) {
+            for (const [id, a] of Object.entries(approvals.approvals ?? {}))
+                signoffs.push({ id, a, file: "approvals.yaml", key: `approvals.${id}` });
+        }
+    }
+    for (const f of storyFiles(approvalsDir(dir))) {
+        const file = `approvals/${f.id}.yaml`;
+        const a = loadYaml(dir, file, errors);
+        if (a === undefined)
+            continue;
+        const wrapped = { format_version: 1, approvals: { [f.id]: a } };
+        if (!checkApprovals(wrapped)) {
+            for (const e of checkApprovals.errors ?? []) {
+                if (e.keyword === "pattern" && e.propertyName)
+                    continue;
+                errors.push({ file, message: describe(e, wrapped).replace(`approvals.${f.id}`, f.id) });
+            }
+            continue;
+        }
+        if (signoffs.some((s) => s.id === f.id))
+            errors.push({ file, message: `${f.id} is also in approvals.yaml`, hint: "keep one: nikos migrate per-story moves every approval to its own file" });
+        signoffs.push({ id: f.id, a, file, key: f.id });
+    }
+    for (const { id, a, file, key } of signoffs) {
+        if (!mapStories.has(id) && !featureIds.has(id)) {
+            errors.push({ file, message: `${key} is an unknown story id` });
+            continue;
+        }
+        const lapse = approvalLapse(a, stateStories[id], hashes.get(id));
+        if (lapse)
+            warnings.push({ file, message: `${id}'s approval no longer holds: ${lapse}`, hint: `once it's done again, a person approves it again (nikos approve ${id}), or remove the entry` });
+    }
+    // Dependencies: each @depends-<id> names a known story, never itself, never in a loop.
+    const statusOf = (id) => stateStories[id]?.status ?? "todo";
+    for (const [id, deps] of dependsOn) {
+        const file = featureIds.get(id);
+        for (const dep of deps) {
+            if (dep === id)
+                errors.push({ file, message: `${id} depends on itself` });
+            else if (!featureIds.has(dep) && !mapStories.has(dep))
+                errors.push({ file, message: `@depends-${dep} names a story that doesn't exist` });
+            else if (statusOf(dep) === "cancelled" && !isDone(statusOf(id)))
+                warnings.push({ file, message: `${id} depends on ${dep}, which is cancelled`, hint: `drop the @depends-${dep} tag, or bring ${dep} back with nikos state set ${dep} todo` });
+            else if ((mapStories.get(dep) ?? 0) > (mapStories.get(id) ?? Infinity)) {
+                warnings.push({ file, message: `${id} in release ${mapStories.get(id)} depends on ${dep}, which is in a later release (${mapStories.get(dep)})`, hint: `move one of them: nikos release move ${dep} ${mapStories.get(id)}` });
+            }
+        }
     }
-    // Bet links: each names a bet in planning/bets/ or one in another repo (owner/repo#id).
+    for (const loop of dependencyLoops(dependsOn)) {
+        errors.push({ file: featureIds.get(loop[0]), message: `stories depend on each other in a loop: ${[...loop, loop[0]].join(" → ")}`, hint: "remove one of the @depends tags" });
+    }
+    // Bet links: each names a bet in planning/bets/ or one in another repo (<repo path>#id).
     if (storymap && typeof storymap === "object") {
         const betsDir = join(planningDir(dir), "bets");
         const check = (where, refs) => {
@@ -183,9 +295,9 @@ export function validate(start) {
                 if (CROSS_REF.test(ref))
                     continue; // another repo's bet: checked for form only, never fetched
                 if (!BET_ID.test(ref)) {
-                    errors.push({ file: "storymap.yaml", message: `${where} names bet '${ref}', which is neither a bet id nor owner/repo#id`, hint: "use a bet id like faster-checkout, or owner/repo#bet-id for another repo's bet" });
+                    errors.push({ file: "storymap.yaml", message: `${where} names bet '${ref}', which is neither a bet id nor <repo path>#id`, hint: "use a bet id like faster-checkout, or owner/repo#bet-id for another repo's bet" });
                 }
-                else if (!existsSync(join(betsDir, `${ref}.md`))) {
+                else if (!store().exists(join(betsDir, `${ref}.md`))) {
                     errors.push({ file: "storymap.yaml", message: `${where} names bet '${ref}', which has no planning/bets/${ref}.md`, hint: "create it with `nikos planning bet new`, or fix the name" });
                 }
             }
@@ -200,6 +312,29 @@ export function validate(start) {
     }
     return { dir, errors, warnings, stories: mapStories.size, releases: storymap?.releases?.length ?? 0 };
 }
+/** Each dependency loop once, starting from its first story in file order. */
+function dependencyLoops(deps) {
+    const loops = [];
+    const seen = new Set();
+    const visit = (id, path) => {
+        const at = path.indexOf(id);
+        if (at >= 0) {
+            const loop = path.slice(at);
+            if (loop.length > 1 && !loops.some((l) => l.length === loop.length && l.every((x) => loop.includes(x))))
+                loops.push(loop);
+            return;
+        }
+        if (seen.has(id))
+            return;
+        for (const dep of deps.get(id) ?? [])
+            if (dep !== id)
+                visit(dep, [...path, id]);
+        seen.add(id);
+    };
+    for (const id of deps.keys())
+        visit(id, []);
+    return loops;
+}
 export function formatResult(r) {
     const lines = [];
     for (const e of r.errors)

package/dist/commands/verify.d.ts

@@ -0,0 +1,20 @@
+import { type Stack } from "../verify/detect.js";
+export interface SetupResult {
+    stack: Stack;
+    created: string[];
+    skipped: string[];
+    install: string;
+}
+/** Write the runner config and step stubs for the repo's stack. Never overwrites a file. */
+export declare function setupVerify(root: string): SetupResult;
+export interface VerifyResult {
+    stack: Stack;
+    command: string;
+    status: number;
+    output: string;
+}
+/** Run the story's scenarios (or all of them) with the repo's Cucumber runner. */
+export declare function verify(root: string, story?: string, opts?: {
+    inherit?: boolean;
+}): VerifyResult;
+export declare function runVerify(args: string[]): number;

package/dist/commands/video.d.ts

@@ -0,0 +1,33 @@
+export interface Storyboard {
+    product: {
+        name: string;
+        idea: string;
+    };
+    users: string;
+    problem: string;
+    /** One beat per activity with done stories, in story map order, timed in seconds. */
+    beats: {
+        activity: string;
+        from: number;
+        to: number;
+        stories: {
+            id: string;
+            title: string;
+            outcomes: string[];
+        }[];
+    }[];
+    notBuilt: {
+        id: string;
+        title: string;
+    }[];
+    intro: [number, number];
+    close: [number, number];
+    total: number;
+}
+/** Draft a video storyboard from intent/: only stories marked done, one beat per activity. */
+export declare function storyboard(dir: string): Storyboard;
+/** The brief a person approves before anything renders. */
+export declare function briefOf(sb: Storyboard): string;
+/** Write brief.md and storyboard.js (read by the Video pack's storyboard template) into `out`. */
+export declare function writeVideo(dir: string, out: string): Storyboard;
+export declare function runVideo(args: string[]): number;

package/dist/commands/video.js

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { loadStates } from "../lib/state-files.js";
 import { join, relative, resolve } from "node:path";
 import { parse } from "yaml";
-import { findIntentDir, featureStoryIds, read, walk } from "../lib/project.js";
+import { findIntentDir, featureStoryIds, isDone, read, walk } from "../lib/project.js";
 import { parseFeature, scenariosOf } from "../lint/gherkin.js";
 // Timing: a title card, then each beat holds longer for more stories, then the close.
 const INTRO = 4.5, BEAT = 2.6, PER_STORY = 1.8, CLOSE = 6;
@@ -23,7 +24,7 @@ export function storyboard(dir) {
     const intentDir = findIntentDir(dir);
     const c = constitution(intentDir);
     const map = parse(read(join(intentDir, "storymap.yaml")));
-    const state = (parse(read(join(intentDir, "state.yaml"))) ?? {});
+    const state = { stories: loadStates(intentDir) };
     const stories = walk(join(intentDir, "features"), ".feature").flatMap((path) => {
         const text = read(path);
         const id = featureStoryIds(text)[0];
@@ -33,7 +34,7 @@ export function storyboard(dir) {
         const activity = feature.tags.map((t) => t.name).find((t) => t.startsWith("@activity-"))?.slice(10) ?? "";
         // "AC1 — A new plant shows its next watering day" → "A new plant shows its next watering day"
         const outcomes = scenariosOf(feature).map((s) => s.name.replace(/^AC\d+\s*[—–-]\s*/, ""));
-        return [{ id, title: feature.name, activity, outcomes, done: state.stories?.[id]?.status === "done" }];
+        return [{ id, title: feature.name, activity, outcomes, done: isDone(state.stories?.[id]?.status) }];
     });
     const byNumber = (a, b) => Number(a.id.split("-")[1]) - Number(b.id.split("-")[1]);
     const done = stories.filter((s) => s.done).sort(byNumber);

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { MemoryStore, diskStore, store, withStore, type Store } from "./lib/store.js";
+export { STORY_ID, DONE, isDone, specHash, findIntentDir } from "./lib/project.js";
+export { loadApprovals, approvalLapse, type Approval } from "./lib/approvals.js";
+export { loadStates, storyState, perStory, type StoryState } from "./lib/state-files.js";
+export { validate, formatResult, type Issue, type ValidationResult } from "./commands/validate.js";
+export { init, keyFor, slugify } from "./commands/init.js";
+export { newStory, type StoryInput, type StoryResult } from "./commands/story.js";
+export { newStep } from "./commands/step.js";
+export { addRelease, renameRelease, moveStory, removeRelease, reorderRelease, checkRelease, type ReleaseCheck } from "./commands/release.js";
+export { setState, StateError, type Status, type StateResult } from "./commands/state.js";
+export { next, dependencies, type NextResult } from "./commands/next.js";
+export { suggest, type Option, type Suggestion } from "./commands/suggest.js";
+export { show } from "./commands/show.js";
+export { clear, featureFor } from "./commands/clear.js";
+export { newPlan, planVersions } from "./commands/plan.js";
+export { decide } from "./commands/decide.js";
+export { decisionEntries, findDecisions } from "./commands/decisions.js";
+export { storyMapOf, renderMap, type StoryMap, type MapStory, type MapRelease } from "./commands/map.js";
+export { exportMap, FORMATS, type Format } from "./commands/export.js";
+export { migrate, type Layout, type MigrateResult } from "./commands/migrate.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+// nikOS as a library: the rules behind the CLI, for tools that work on a repo's files without a
+// shell. Load the files into a MemoryStore, run commands inside withStore, then commit
+// store.changes(). Running scenarios (done, approve, verify) needs a real checkout, so tools
+// without one leave that to CI.
+export { MemoryStore, diskStore, store, withStore } from "./lib/store.js";
+export { STORY_ID, DONE, isDone, specHash, findIntentDir } from "./lib/project.js";
+export { loadApprovals, approvalLapse } from "./lib/approvals.js";
+export { loadStates, storyState, perStory } from "./lib/state-files.js";
+export { validate, formatResult } from "./commands/validate.js";
+export { init, keyFor, slugify } from "./commands/init.js";
+export { newStory } from "./commands/story.js";
+export { newStep } from "./commands/step.js";
+export { addRelease, renameRelease, moveStory, removeRelease, reorderRelease, checkRelease } from "./commands/release.js";
+export { setState, StateError } from "./commands/state.js";
+export { next, dependencies } from "./commands/next.js";
+export { suggest } from "./commands/suggest.js";
+export { show } from "./commands/show.js";
+export { clear, featureFor } from "./commands/clear.js";
+export { newPlan, planVersions } from "./commands/plan.js";
+export { decide } from "./commands/decide.js";
+export { decisionEntries, findDecisions } from "./commands/decisions.js";
+export { storyMapOf, renderMap } from "./commands/map.js";
+export { exportMap, FORMATS } from "./commands/export.js";
+export { migrate } from "./commands/migrate.js";

package/dist/lib/approvals.d.ts

@@ -0,0 +1,29 @@
+export interface Approval {
+    by: string;
+    on: string;
+    /** How it was given: typed in a terminal, answered in a chat with an agent, or asked by nikos mcp through the person's app. */
+    via?: "terminal" | "chat" | "app" | "tracker";
+    /** The feature fingerprint that was approved. */
+    spec_hash: string;
+    /** Which time the story reached done: going through done again needs a new approval. */
+    done_at: string;
+}
+export declare const approvalsPath: (intentDir: string) => string;
+export declare function loadApprovals(intentDir: string): Record<string, Approval>;
+/**
+ * Which done a story is on. Stories done before done_at existed fall back to the date of their
+ * last move, which stays put while they stay done.
+ */
+export declare const doneMark: (state: {
+    done_at?: string;
+    updated?: string;
+} | undefined) => string;
+/**
+ * Whether an approval still holds for a story's current state. It holds while the story is done,
+ * since the same done, with the same feature. Returns undefined when it holds, or why not.
+ */
+export declare function approvalLapse(approval: Approval, state: {
+    status?: string;
+    done_at?: string;
+    updated?: string;
+} | undefined, currentHash: string | undefined): string | undefined;

package/dist/lib/approvals.js

@@ -0,0 +1,28 @@
+// Approvals live in intent/approvals.yaml (or intent/approvals/<ID>.yaml, one per story), apart
+// from story state, so a repo can protect them: a CODEOWNERS rule on them means an approval only
+// lands when the right person reviews the PR or merge request. Agents write state all the time;
+// approvals only change on sign-off.
+import { join } from "node:path";
+import { loadApprovalEntries } from "./state-files.js";
+export const approvalsPath = (intentDir) => join(intentDir, "approvals.yaml");
+export function loadApprovals(intentDir) {
+    return loadApprovalEntries(intentDir);
+}
+/**
+ * Which done a story is on. Stories done before done_at existed fall back to the date of their
+ * last move, which stays put while they stay done.
+ */
+export const doneMark = (state) => String(state?.done_at ?? state?.updated ?? "unknown");
+/**
+ * Whether an approval still holds for a story's current state. It holds while the story is done,
+ * since the same done, with the same feature. Returns undefined when it holds, or why not.
+ */
+export function approvalLapse(approval, state, currentHash) {
+    if (state?.status !== "done")
+        return state ? `it's ${state.status} now` : "it has no entry in state";
+    if (approval.done_at !== doneMark(state))
+        return "it went through done again since";
+    if (currentHash && approval.spec_hash !== currentHash)
+        return "its feature changed since";
+    return undefined;
+}

package/dist/lib/bets.d.ts

@@ -0,0 +1,21 @@
+/** A bet in this repo: lowercase words joined by hyphens. */
+export declare const BET_ID: RegExp;
+/**
+ * Another repo, as its path on the host: owner/repo on GitHub, or group/subgroup/project on
+ * GitLab, with as many groups as it has.
+ */
+export declare const REPO_PATH: RegExp;
+/** A bet or key result in another repo: <repo path>#id, e.g. acme/company-plan#d30-retention. */
+export declare const CROSS_REF: RegExp;
+export declare const isBetRef: (ref: string) => boolean;
+/** The repo's planning/ folder, next to intent/. */
+export declare const planningDir: (intentDir: string) => string;
+export interface StoryBets {
+    bets: string[];
+    from: "story" | "release" | "none";
+    release?: number;
+}
+/** The bets a story delivers: its own `story_bets` entry, or else its release's `bets`. */
+export declare function betsFor(map: any, story: string): StoryBets;
+/** Every story that delivers a bet, after story overrides. */
+export declare function storiesFor(map: any, bet: string): string[];

package/dist/lib/bets.js

@@ -3,8 +3,15 @@
 import { dirname, join } from "node:path";
 /** A bet in this repo: lowercase words joined by hyphens. */
 export const BET_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-/** A bet or key result in another repo: owner/repo#id. */
-export const CROSS_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[a-z0-9]+(-[a-z0-9]+)*$/;
+/** One part of a repo path; "." and ".." are never allowed, so a path can't leave .nikos/upstream/. */
+const SEGMENT = String.raw `(?!\.{1,2}(?:/|#|$))[A-Za-z0-9_.-]+`;
+/**
+ * Another repo, as its path on the host: owner/repo on GitHub, or group/subgroup/project on
+ * GitLab, with as many groups as it has.
+ */
+export const REPO_PATH = new RegExp(`^${SEGMENT}(?:/${SEGMENT})+$`);
+/** A bet or key result in another repo: <repo path>#id, e.g. acme/company-plan#d30-retention. */
+export const CROSS_REF = new RegExp(`^${SEGMENT}(?:/${SEGMENT})+#[a-z0-9]+(-[a-z0-9]+)*$`);
 export const isBetRef = (ref) => BET_ID.test(ref) || CROSS_REF.test(ref);
 /** The repo's planning/ folder, next to intent/. */
 export const planningDir = (intentDir) => join(dirname(intentDir), "planning");

package/dist/lib/frontmatter.d.ts

@@ -0,0 +1,5 @@
+/** Split a Markdown file into its YAML front matter and body. */
+export declare function parseFrontMatter(text: string): {
+    meta: any;
+    body: string;
+} | undefined;

package/dist/lib/project.d.ts

@@ -0,0 +1,25 @@
+export declare const STORY_ID: RegExp;
+/** Statuses that count as built. approved is how the map shows done plus a sign-off that holds. */
+export declare const DONE: Set<string>;
+export declare const isDone: (status: string | undefined) => boolean;
+/**
+ * A short fingerprint of what a story promises: the feature from `Feature:` on. The tags above
+ * it are left out, so moving a story between releases or adding a @depends tag isn't a change.
+ */
+export declare function specHash(text: string): string;
+/** Resolve the intent/ folder from a repo root or the folder itself. */
+export declare function findIntentDir(start: string): string;
+export declare function walk(dir: string, ext?: string): string[];
+export declare function read(path: string): string;
+export declare function rel(dir: string, path: string): string;
+/** The value of a `@<name>-<value>` tag above `Feature:`, e.g. featureTag(text, "step"). */
+export declare function featureTag(text: string, name: string): string | undefined;
+/** Every value of a repeatable `@<name>-<value>` tag above `Feature:`, e.g. featureTags(text, "depends"). */
+export declare function featureTags(text: string, name: string): string[];
+/**
+ * Set (or with value undefined, remove) a `@<name>-<value>` tag above `Feature:`. An existing tag
+ * is replaced where it stands; a new one goes after the tag `after` (e.g. the story id), or last.
+ */
+export declare function setFeatureTag(text: string, name: string, value: string | undefined, after?: string): string;
+/** Story id tags on the lines above `Feature:`. */
+export declare function featureStoryIds(text: string): string[];

package/dist/lib/project.js

@@ -1,34 +1,51 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { store } from "./store.js";
 import { join, relative } from "node:path";
 export const STORY_ID = /^[A-Z][A-Z0-9]{0,9}-[0-9]+$/;
+/** Statuses that count as built. approved is how the map shows done plus a sign-off that holds. */
+export const DONE = new Set(["done", "approved"]);
+export const isDone = (status) => DONE.has(status ?? "");
+/**
+ * A short fingerprint of what a story promises: the feature from `Feature:` on. The tags above
+ * it are left out, so moving a story between releases or adding a @depends tag isn't a change.
+ */
+export function specHash(text) {
+    const at = text.search(/^\s*Feature:/m);
+    const spec = (at < 0 ? text : text.slice(at)).replace(/\r\n/g, "\n").split("\n").map((l) => l.trimEnd()).join("\n").trim();
+    return createHash("sha256").update(spec).digest("hex").slice(0, 12);
+}
 /** Resolve the intent/ folder from a repo root or the folder itself. */
 export function findIntentDir(start) {
-    if (existsSync(join(start, "storymap.yaml")))
+    if (store().exists(join(start, "storymap.yaml")))
         return start;
     return join(start, "intent");
 }
 export function walk(dir, ext) {
-    if (!existsSync(dir))
+    if (!store().exists(dir))
         return [];
-    return readdirSync(dir).flatMap((f) => {
+    return store().list(dir).flatMap((f) => {
         const p = join(dir, f);
-        if (statSync(p).isDirectory())
+        if (store().isDir(p))
             return walk(p, ext);
         return !ext || p.endsWith(ext) ? [p] : [];
     });
 }
 export function read(path) {
-    return readFileSync(path, "utf8");
+    return store().read(path);
 }
 export function rel(dir, path) {
     return relative(dir, path) || path;
 }
-/** Story id tags on the lines above `Feature:`. */
 /** The value of a `@<name>-<value>` tag above `Feature:`, e.g. featureTag(text, "step"). */
 export function featureTag(text, name) {
     const head = text.split(/^\s*Feature:/m)[0];
     return new RegExp(`(?:^|\\s)@${name}-([A-Za-z0-9-]+)`).exec(head)?.[1];
 }
+/** Every value of a repeatable `@<name>-<value>` tag above `Feature:`, e.g. featureTags(text, "depends"). */
+export function featureTags(text, name) {
+    const head = text.split(/^\s*Feature:/m)[0];
+    return [...head.matchAll(new RegExp(`(?:^|\\s)@${name}-([A-Za-z0-9-]+)`, "g"))].map((m) => m[1]);
+}
 /**
  * Set (or with value undefined, remove) a `@<name>-<value>` tag above `Feature:`. An existing tag
  * is replaced where it stands; a new one goes after the tag `after` (e.g. the story id), or last.
@@ -61,6 +78,7 @@ export function setFeatureTag(text, name, value, after) {
     }
     return lines.join("\n");
 }
+/** Story id tags on the lines above `Feature:`. */
 export function featureStoryIds(text) {
     const ids = [];
     for (const line of text.split("\n")) {

package/dist/lib/settings.d.ts

@@ -0,0 +1,29 @@
+export declare const SETTINGS_FILE = "nikos.settings.yaml";
+export type ApprovalPolicy = "off" | "optional" | "required-for-release";
+export type ApprovalRoute = "app" | "chat" | "terminal";
+/** Every setting nikOS knows, with its default. Keys are dotted paths into the file. */
+export declare const DEFAULTS: Record<string, unknown>;
+export interface Setting {
+    value: unknown;
+    /** "default", "this repo", or the repo path of the level it came from. */
+    from: string;
+    /** The level that locked it, if one did. */
+    lockedBy?: string;
+}
+export type Resolved = Record<string, Setting>;
+/** A repo's own settings file, parsed and checked. */
+export declare function readSettings(root: string): {
+    values: Record<string, unknown>;
+    locked: string[];
+};
+/**
+ * The settings that apply to a repo: defaults, then each level above it from the top down
+ * (through the synced copies in .nikos/upstream/), then the repo's own. A level can't change a
+ * value a level above it locked.
+ */
+export declare function resolveSettings(root: string): Resolved;
+export declare const settingValue: <T>(root: string, key: string) => T;
+/** Change a setting in this repo's own file, unless a level above locked it. */
+export declare function setSetting(root: string, key: string, value: unknown): string;
+/** The settings as lines: each value, where it came from, and whether it's locked. */
+export declare function formatSettings(r: Resolved): string;