nikos 0.1.0 → 0.2.0

package/dist/commands/doctor.js

@@ -0,0 +1,92 @@
+// `nikos doctor`: is this repo set up the way nikOS works best? Each check says what it found
+// and, when something's missing, the next thing to do, in words an agent can act on.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findIntentDir } from "../lib/project.js";
+import { resolveSettings } from "../lib/settings.js";
+import { store } from "../lib/store.js";
+import { perStory } from "../lib/state-files.js";
+import { detectStack } from "../verify/detect.js";
+import { checkStale, readLock, upstreamEntries } from "../planning/upstream.js";
+import { validate } from "./validate.js";
+const CI_FILES = [".github/workflows/nikos.yml", ".gitlab/ci/nikos.yml"];
+const RUNNER_FILES = ["cucumber.mjs", "cucumber.js", "behave.ini"];
+/** The repo's CODEOWNERS file, wherever GitHub or GitLab looks for it. */
+const codeowners = (root) => ["CODEOWNERS", ".github/CODEOWNERS", ".gitlab/CODEOWNERS", "docs/CODEOWNERS"].map((f) => join(root, f)).find((f) => existsSync(f));
+export function doctor(root, opts = {}) {
+    const checks = [];
+    const add = (c) => checks.push(c);
+    const intent = findIntentDir(root);
+    if (!store().exists(join(intent, "storymap.yaml"))) {
+        add({ name: "story map", status: "fail", found: "no intent/ folder", next: "Set up nikOS here (nikos init), or map what the repo already does" });
+        return checks;
+    }
+    const v = validate(root);
+    add(v.errors.length
+        ? { name: "story map", status: "fail", found: `${v.errors.length} ${v.errors.length === 1 ? "problem" : "problems"} in intent/`, next: "Run nikos validate and fix what it lists" }
+        : { name: "story map", status: v.warnings.length ? "warn" : "ok", found: `${v.stories} stories in ${v.releases} releases${v.warnings.length ? `, ${v.warnings.length} warnings` : ""}`, ...(v.warnings.length ? { next: "Run nikos validate to see the warnings" } : {}) });
+    const runner = RUNNER_FILES.find((f) => existsSync(join(root, f)));
+    add(runner
+        ? { name: "scenario runner", status: "ok", found: runner }
+        : { name: "scenario runner", status: "fail", found: detectStack(root) ? "no Cucumber runner yet" : "no runner, and the stack isn't clear", next: "Set one up with nikos verify setup, so stories can be proved done" });
+    const ci = CI_FILES.find((f) => existsSync(join(root, f)));
+    add(ci ? { name: "CI", status: "ok", found: ci } : { name: "CI", status: "warn", found: "scenarios don't run on pull or merge requests", next: "Add the pipeline with nikos ci setup" });
+    const settings = resolveSettings(root);
+    const policy = settings["approval.policy"];
+    const owners = codeowners(root);
+    const protectedApprovals = owners && /approvals(\.yaml|\/)/.test(readFileSync(owners, "utf8"));
+    if (policy.value === "off")
+        add({ name: "approvals", status: "ok", found: `off (${policy.from})` });
+    else if (protectedApprovals)
+        add({ name: "approvals", status: "ok", found: `${policy.value} (${policy.from}); intent/approvals${perStory(intent) ? "/" : ".yaml"} needs a CODEOWNERS review` });
+    else
+        add({
+            name: "approvals",
+            status: policy.value === "required-for-release" ? "warn" : "ok",
+            found: `${policy.value} (${policy.from}); anyone can add an approval`,
+            ...(policy.value === "required-for-release" ? { next: "Protect intent/approvals.yaml with a CODEOWNERS rule and branch protection, so an approval needs the right reviewer" } : {}),
+        });
+    const tracker = settings["tracker.system"];
+    if (tracker.value !== "none") {
+        const mapped = Object.keys(settings["tracker.statuses"].value).length;
+        add(mapped
+            ? { name: "tracker", status: "ok", found: `${tracker.value} (${tracker.from}), ${mapped} statuses mapped` }
+            : { name: "tracker", status: "warn", found: `${tracker.value}, but no statuses mapped`, next: "Connect the tracker: map its statuses to nikOS's" });
+    }
+    let upstreams = [];
+    try {
+        upstreams = upstreamEntries(root).map((e) => e.repo);
+    }
+    catch (err) {
+        add({ name: "upstream plans", status: "fail", found: err.message, next: "Fix planning/upstream.yaml" });
+    }
+    if (upstreams.length) {
+        const lock = readLock(root);
+        const missing = upstreams.filter((r) => !lock.some((l) => l.repo === r));
+        if (missing.length)
+            add({ name: "upstream plans", status: "warn", found: `${missing.join(", ")} not synced yet`, next: "Run nikos planning sync" });
+        else if (!opts.offline) {
+            const stale = checkStale(root);
+            const problems = [...stale.stale.map((s) => `${s.repo} has moved on`), ...stale.unresolved.map((u) => `${u.repo} unreachable`)];
+            add(problems.length ? { name: "upstream plans", status: "warn", found: problems.join("; "), next: "Run nikos planning sync" } : { name: "upstream plans", status: "ok", found: `${lock.length} synced and current` });
+        }
+        else
+            add({ name: "upstream plans", status: "ok", found: `${lock.length} synced` });
+    }
+    return checks;
+}
+export function runDoctor(args) {
+    const i = args.indexOf("--dir");
+    const root = i >= 0 ? args[i + 1] : process.cwd();
+    try {
+        const checks = doctor(root, { offline: args.includes("--offline") });
+        const mark = { ok: "✓", warn: "!", fail: "✗" };
+        for (const c of checks)
+            console.log(`${mark[c.status]} ${c.name}: ${c.found}${c.next ? `\n    → ${c.next}` : ""}`);
+        return checks.some((c) => c.status === "fail") ? 1 : 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/export.d.ts

@@ -0,0 +1,48 @@
+import { type StoryMap } from "./map.js";
+export declare const FORMATS: readonly ["prd", "linear", "jira"];
+export type Format = (typeof FORMATS)[number];
+export declare function toPrd(m: StoryMap): string;
+/** One Linear issue per story; releases become milestones. State and labels are names to map to ids. */
+export declare function toLinear(m: StoryMap): {
+    format: string;
+    project: string;
+    milestones: {
+        name: string;
+        description: string;
+    }[];
+    issues: {
+        stateName: string;
+        milestoneName: string;
+        labelNames: string[];
+        blockedBy: string[];
+        estimate?: number | undefined;
+        externalId: string;
+        title: string;
+        description: string;
+        priority: number;
+    }[];
+};
+/** The body of Jira's bulk create (POST /rest/api/2/issue/bulk). Jira can't set status on create. */
+export declare function toJira(m: StoryMap, projectKey: string): {
+    issueUpdates: {
+        fields: {
+            labels: string[];
+            priority?: {
+                name: string;
+            } | undefined;
+            project: {
+                key: string;
+            };
+            summary: string;
+            description: string;
+            issuetype: {
+                name: string;
+            };
+        };
+    }[];
+};
+export declare function exportMap(dir: string, format: Format, opts?: {
+    release?: number;
+    projectKey?: string;
+}): string;
+export declare function runExport(args: string[]): number;

package/dist/commands/export.js

@@ -0,0 +1,164 @@
+// `nikos export`: the story map in a shape another tool reads. A PRD in Markdown for people;
+// JSON for Linear (one issue per story, fields named as in Linear's IssueCreateInput) and Jira
+// (the body of POST /rest/api/2/issue/bulk). intent/ stays the source: these are copies.
+import { writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { isDone } from "../lib/project.js";
+import { storyMapOf } from "./map.js";
+export const FORMATS = ["prd", "linear", "jira"];
+const STATUS_WORD = {
+    todo: "To do",
+    in_progress: "In progress",
+    needs_rework: "Needs rework",
+    done: "Done",
+    approved: "Approved",
+    cancelled: "Cancelled",
+};
+const TYPE_WORD = { user_story: "User story", technical: "Technical", bug_risk: "Bug risk" };
+const label = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+const live = (r) => r.stories.filter((s) => s.status !== "cancelled");
+function activityOf(m, s) {
+    const a = m.activities.find((x) => x.id === s.activity);
+    return { activity: a?.title ?? s.activity, step: a?.steps.find((st) => st.id === s.step)?.title ?? s.step };
+}
+/** The facts line under a story: status, type, priority, effort, personas, dependencies. */
+function facts(m, s) {
+    const persona = (id) => m.personas.find((p) => p.id === id)?.title ?? id;
+    const { activity, step } = activityOf(m, s);
+    return [
+        `Status: ${STATUS_WORD[s.status] ?? s.status}${s.status === "approved" && s.approvedBy ? ` by ${s.approvedBy}` : ""}`,
+        TYPE_WORD[s.type] && s.type !== "user_story" ? `Type: ${TYPE_WORD[s.type]}` : "",
+        s.priority && `Priority: ${s.priority}`,
+        s.effort && `Effort: ${s.effort}`,
+        activity && `Activity: ${activity}${step ? ` › ${step}` : ""}`,
+        s.personas.length ? `For: ${s.personas.map(persona).join(", ")}` : "",
+        s.dependsOn.length ? `Depends on: ${s.dependsOn.join(", ")}` : "",
+    ].filter(Boolean);
+}
+export function toPrd(m) {
+    const out = [`# ${m.project || "Product"}: product requirements`, "", "Exported from the nikOS story map (intent/storymap.yaml). Edit the story map, not this file.", ""];
+    if (m.personas.length) {
+        out.push("## Who it's for", "");
+        for (const p of m.personas)
+            out.push(`- **${p.title}**${p.description ? `: ${p.description}` : ""}`);
+        out.push("");
+    }
+    for (const r of m.releases) {
+        const stories = live(r);
+        out.push(`## Release ${r.number}: ${r.title}`, "");
+        if (r.goal)
+            out.push(`**Goal:** ${r.goal}`, "");
+        if (r.bets.length)
+            out.push(`**Delivers:** ${r.bets.join(", ")}`, "");
+        out.push(`${stories.filter((s) => isDone(s.status)).length} of ${stories.length} ${stories.length === 1 ? "story" : "stories"} done.`, "");
+        for (const s of stories) {
+            out.push(`### ${s.id}: ${s.title}`, "");
+            if (s.narrative)
+                out.push(s.narrative, "");
+            out.push(facts(m, s).join(" · "), "");
+            if (s.criteria.length) {
+                out.push("Acceptance criteria:", "");
+                for (const c of s.criteria)
+                    out.push(`- ${c.id ? `${c.id}: ` : ""}${c.title}${c.priority ? ` (${c.priority})` : ""}`);
+                out.push("");
+            }
+        }
+    }
+    const cancelled = m.releases.flatMap((r) => r.stories).filter((s) => s.status === "cancelled");
+    if (cancelled.length) {
+        out.push("## Cancelled", "");
+        for (const s of cancelled)
+            out.push(`- ${s.id}: ${s.title}${s.cancelledReason ? `. ${s.cancelledReason}` : ""}`);
+        out.push("");
+    }
+    return out.join("\n");
+}
+/** A story's description as Markdown (Linear) or Jira wiki markup. */
+function body(m, s, wiki) {
+    const lines = [s.narrative, "", ...facts(m, s).map((f) => (wiki ? `* ${f}` : `- ${f}`))];
+    if (s.criteria.length) {
+        lines.push("", wiki ? "h3. Acceptance criteria" : "### Acceptance criteria");
+        for (const c of s.criteria)
+            lines.push(`${wiki ? "#" : "1."} ${c.id ? `${c.id}: ` : ""}${c.title}${c.priority ? ` (${c.priority})` : ""}`);
+    }
+    return lines.join("\n").trim();
+}
+const LINEAR_PRIORITY = { must: 2, should: 3, could: 4 };
+const ESTIMATE = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
+const LINEAR_STATE = { todo: "Todo", in_progress: "In Progress", needs_rework: "In Progress", done: "Done", approved: "Done" };
+/** One Linear issue per story; releases become milestones. State and labels are names to map to ids. */
+export function toLinear(m) {
+    return {
+        format: "nikos-linear/1",
+        project: m.project,
+        milestones: m.releases.map((r) => ({ name: `Release ${r.number}: ${r.title}`, description: r.goal })),
+        issues: m.releases.flatMap((r) => live(r).map((s) => {
+            const { activity, step } = activityOf(m, s);
+            return {
+                externalId: s.id,
+                title: `${s.id} ${s.title}`,
+                description: body(m, s, false),
+                priority: LINEAR_PRIORITY[s.priority] ?? 0,
+                ...(ESTIMATE[s.effort] ? { estimate: ESTIMATE[s.effort] } : {}),
+                stateName: LINEAR_STATE[s.status] ?? "Todo",
+                milestoneName: `Release ${r.number}: ${r.title}`,
+                labelNames: [activity, step, s.type !== "user_story" ? TYPE_WORD[s.type] : "", ...s.personas].filter(Boolean),
+                blockedBy: s.dependsOn,
+            };
+        })),
+    };
+}
+const JIRA_PRIORITY = { must: "High", should: "Medium", could: "Low" };
+/** The body of Jira's bulk create (POST /rest/api/2/issue/bulk). Jira can't set status on create. */
+export function toJira(m, projectKey) {
+    return {
+        issueUpdates: m.releases.flatMap((r) => live(r).map((s) => ({
+            fields: {
+                project: { key: projectKey },
+                summary: `${s.id} ${s.title}`,
+                description: body(m, s, true),
+                issuetype: { name: s.type === "user_story" ? "Story" : "Task" },
+                ...(JIRA_PRIORITY[s.priority] ? { priority: { name: JIRA_PRIORITY[s.priority] } } : {}),
+                labels: [`nikos-${label(s.id)}`, `release-${r.number}`, label(s.activity), label(s.step), s.type !== "user_story" ? label(s.type) : "", `status-${label(s.status)}`, ...s.personas.map(label)].filter(Boolean),
+            },
+        }))),
+    };
+}
+export function exportMap(dir, format, opts = {}) {
+    if (!FORMATS.includes(format))
+        throw new Error(`'${format}' is not a format (${FORMATS.join(", ")})`);
+    const full = storyMapOf(dir);
+    if (opts.release !== undefined && !full.releases.some((r) => r.number === opts.release)) {
+        throw new Error(`There is no release ${opts.release}. Releases: ${full.releases.map((r) => r.number).join(", ")}`);
+    }
+    const m = opts.release === undefined ? full : { ...full, releases: full.releases.filter((r) => r.number === opts.release) };
+    if (format === "prd")
+        return toPrd(m);
+    const json = format === "linear" ? toLinear(m) : toJira(m, opts.projectKey ?? (full.key || "PROJ"));
+    return JSON.stringify(json, null, 2) + "\n";
+}
+const DEFAULT_OUT = { prd: "storymap-prd.md", linear: "storymap-linear.json", jira: "storymap-jira.json" };
+export function runExport(args) {
+    const flag = (name) => {
+        const i = args.indexOf(`--${name}`);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const format = flag("format");
+    if (!format) {
+        console.error('Usage: nikos export --format <prd|linear|jira> [--release <n>] [--out <file>] [--project-key <KEY>] [--dir <path>]');
+        return 1;
+    }
+    try {
+        const release = flag("release");
+        const text = exportMap(resolve(flag("dir") ?? process.cwd()), format, { release: release === undefined ? undefined : Number(release), projectKey: flag("project-key") });
+        const out = resolve(flag("out") ?? DEFAULT_OUT[format]);
+        writeFileSync(out, text);
+        const shown = relative(process.cwd(), out);
+        console.log(`Wrote ${shown && !shown.startsWith("..") ? shown : out}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,16 @@
+import { type ValidationResult } from "./validate.js";
+export interface InitOptions {
+    name?: string;
+    key?: string;
+}
+export interface InitResult {
+    intentDir: string;
+    created: string[];
+    skipped: string[];
+    validation: ValidationResult;
+}
+export declare function slugify(name: string): string;
+/** "Hello Todo" → "HT", "nikos" → "NIK". */
+export declare function keyFor(name: string): string;
+export declare function init(root: string, opts?: InitOptions): InitResult;
+export declare function runInit(args: string[]): number;

package/dist/commands/init.js

@@ -1,7 +1,8 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { walk } from "../lib/project.js";
+import { diskStore, store, withStore } from "../lib/store.js";
 import { validate, formatResult } from "./validate.js";
 const here = dirname(fileURLToPath(import.meta.url));
 const templateDir = [join(here, "../../templates/intent"), join(here, "../templates/intent")].find((d) => existsSync(d));
@@ -24,30 +25,32 @@ export function init(root, opts = {}) {
     const intentDir = join(root, "intent");
     const created = [];
     const skipped = [];
-    for (const src of walk(templateDir)) {
+    // The templates ship with nikOS, so they're always listed and read from disk.
+    for (const src of withStore(diskStore, () => walk(templateDir))) {
         const rel = relative(templateDir, src);
         const dest = join(intentDir, rel);
-        if (existsSync(dest)) {
+        if (store().exists(dest)) {
             skipped.push(rel);
             continue;
         }
-        mkdirSync(dirname(dest), { recursive: true });
-        if (rel.endsWith(".gitkeep")) {
-            copyFileSync(src, dest);
-        }
-        else {
-            const text = readFileSync(src, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => values[k] ?? `{{${k}}}`);
-            // "wx" guards against a race where the file appears between the check and the write.
-            writeFileSync(dest, text, { flag: "wx" });
-        }
+        const text = readFileSync(src, "utf8").replace(/\{\{(\w+)\}\}/g, (_, k) => values[k] ?? `{{${k}}}`);
+        // create guards against a race where the file appears between the check and the write.
+        store().write(dest, text, { create: true });
         created.push(rel);
     }
     return { intentDir, created, skipped, validation: validate(intentDir) };
 }
+const EXAMPLES = { name: '"Hello Todo"', key: "HT", dir: "." };
 export function runInit(args) {
     const opt = (n) => {
         const i = args.indexOf(`--${n}`);
-        return i >= 0 ? args[i + 1] : undefined;
+        if (i < 0)
+            return undefined;
+        const value = args[i + 1];
+        // Without this, a bare --name falls back to the folder name and the key changes silently.
+        if (value === undefined || value.startsWith("--") || !value.trim())
+            throw new Error(`--${n} needs a value, e.g. --${n} ${EXAMPLES[n] ?? "<value>"}`);
+        return value;
     };
     try {
         const r = init(opt("dir") ?? process.cwd(), { name: opt("name"), key: opt("key") });

package/dist/commands/join.d.ts

@@ -0,0 +1,17 @@
+import { type Resolved } from "../lib/settings.js";
+import { type SyncReport } from "../planning/upstream.js";
+export interface JoinResult {
+    repo: string;
+    added: boolean;
+    sync: SyncReport;
+    settings: Resolved;
+}
+/** Add an upstream plan to planning/upstream.yaml (if it isn't there), sync, and resolve the settings. */
+export declare function joinPlan(root: string, input: {
+    repo: string;
+    host?: string;
+    url?: string;
+    ref?: string;
+}): JoinResult;
+export declare function runJoin(args: string[]): number;
+export declare function runSettings(args: string[]): number;

package/dist/commands/join.js

@@ -0,0 +1,91 @@
+// `nikos join` and `nikos settings`: link this repo to the plan above it, and see or change the
+// settings it inherits. Joining is one line in planning/upstream.yaml plus a sync; nothing in
+// the repo moves, so a team that started on its own keeps everything it has.
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+import { REPO_PATH } from "../lib/bets.js";
+import { formatSettings, resolveSettings, setSetting } from "../lib/settings.js";
+import { store } from "../lib/store.js";
+import { sync, upstreamEntries } from "../planning/upstream.js";
+/** Add an upstream plan to planning/upstream.yaml (if it isn't there), sync, and resolve the settings. */
+export function joinPlan(root, input) {
+    if (!REPO_PATH.test(input.repo))
+        throw new Error(`'${input.repo}' is not a repo path (owner/repo, or group/subgroup/project on GitLab)`);
+    const path = join(root, "planning", "upstream.yaml");
+    const added = !upstreamEntries(root).some((e) => e.repo === input.repo);
+    if (added) {
+        const before = store().exists(path) ? store().read(path) : undefined;
+        const doc = parseDocument(before ?? "# Plans in other repos this one works toward. nikos planning sync reads them.\n[]\n");
+        const entry = { repo: input.repo, ...(input.ref ? { ref: input.ref } : {}), ...(input.host ? { host: input.host } : {}), ...(input.url ? { url: input.url } : {}) };
+        if (!doc.contents || !("items" in doc.contents))
+            doc.contents = doc.createNode([]);
+        doc.contents.flow = false;
+        doc.contents.items.push(doc.createNode(entry));
+        store().write(path, doc.toString({ lineWidth: 0 }));
+        try {
+            upstreamEntries(root); // a bad host or url fails here, before anything is fetched
+        }
+        catch (err) {
+            store().write(path, before ?? "[]\n");
+            throw err;
+        }
+    }
+    const report = sync(root);
+    return { repo: input.repo, added, sync: report, settings: resolveSettings(root) };
+}
+export function runJoin(args) {
+    const flag = (n) => {
+        const i = args.indexOf(`--${n}`);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const repo = args.find((a, i) => !a.startsWith("--") && !(i > 0 && args[i - 1].startsWith("--")));
+    if (!repo) {
+        console.error("Usage: nikos join <owner/repo | group/subgroup/project> [--host gitlab.com] [--url <git url>] [--ref <branch>] [--dir <path>]");
+        return 1;
+    }
+    try {
+        const r = joinPlan(flag("dir") ?? process.cwd(), { repo, host: flag("host"), url: flag("url"), ref: flag("ref") });
+        console.log(r.added ? `Joined ${r.repo}: added to planning/upstream.yaml` : `Already joined to ${r.repo}`);
+        for (const s of r.sync.synced)
+            console.log(`  ✓ ${s.repo} at ${s.commit.slice(0, 7)}${s.via ? ` (above ${s.via})` : ""}`);
+        for (const u of r.sync.unresolved)
+            console.log(`  ? ${u.repo}: ${u.reason}`);
+        console.log(`\nSettings here now:\n${formatSettings(r.settings)}`);
+        return r.sync.unresolved.some((u) => u.repo === r.repo) ? 1 : 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}
+/** Read a value given on the command line: JSON when it parses (true, ["app","chat"]), else text; a, b, c is a list. */
+const valueOf = (raw) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw.includes(",") ? raw.split(",").map((s) => s.trim()).filter(Boolean) : raw;
+    }
+};
+export function runSettings(args) {
+    const i = args.indexOf("--dir");
+    const root = i >= 0 ? args[i + 1] : process.cwd();
+    const [sub = "show", key, raw] = args.filter((a, n) => a !== "--dir" && (i < 0 || n !== i + 1));
+    try {
+        if (sub === "show") {
+            console.log(formatSettings(resolveSettings(root)));
+            return 0;
+        }
+        if (sub === "set" && key && raw !== undefined) {
+            setSetting(root, key, valueOf(raw));
+            console.log(`${key}: ${JSON.stringify(resolveSettings(root)[key].value)}  (this repo)`);
+            return 0;
+        }
+        console.error("Usage: nikos settings [show] | nikos settings set <key> <value> [--dir <path>]");
+        return 1;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/map.d.ts

@@ -0,0 +1,65 @@
+export interface MapCriterion {
+    id: string;
+    title: string;
+    priority: string;
+}
+export interface MapStory {
+    id: string;
+    title: string;
+    activity: string;
+    /** The step within the activity, or "" when the story has none. */
+    step: string;
+    status: string;
+    blocked: boolean;
+    priority: string;
+    effort: string;
+    /** The user story sentence: As a…, I want…, So that…. */
+    narrative: string;
+    criteria: MapCriterion[];
+    /** user_story (the default), technical or bug_risk, from a @type- tag. */
+    type: string;
+    personas: string[];
+    dependsOn: string[];
+    /** Dependencies that aren't done or approved yet. */
+    waitingOn: string[];
+    /** The feature changed after the story was done or approved. */
+    specChanged: boolean;
+    approvedBy: string;
+    cancelledReason: string;
+}
+export interface MapRelease {
+    number: number;
+    title: string;
+    goal: string;
+    bets: string[];
+    stories: MapStory[];
+}
+export interface StoryMap {
+    project: string;
+    key: string;
+    personas: {
+        id: string;
+        title: string;
+        description: string;
+    }[];
+    activities: {
+        id: string;
+        title: string;
+        steps: {
+            id: string;
+            title: string;
+        }[];
+    }[];
+    releases: MapRelease[];
+    /** Stories with a feature file that no release names. */
+    unreleased: MapStory[];
+}
+export declare const esc: (s: unknown) => string;
+/** The story map as data: activities, releases with their bets, and every story's status. */
+export declare function storyMapOf(dir: string): StoryMap;
+/** The whole story map as one standalone HTML page. live adds the dashboard's filter bar and its script. */
+export declare function renderMap(dir: string, opts?: {
+    live?: boolean;
+}): string;
+/** `nikos map`: write the story map as a standalone page. */
+export declare function runMap(args: string[]): number;