nikos 0.1.0 → 0.2.0

package/dist/planning/rollout.js

@@ -0,0 +1,206 @@
+// `nikos planning rollout`: how the plans below this one are doing. planning/downstream.yaml
+// lists the departments and teams that plan against this repo; rollout fetches a read-only copy
+// of each into .nikos/downstream/<repo path>/ (gitignored), and of the ones they list in turn,
+// and reports for each: has it joined, when did it last sync this plan, how is its delivery
+// going, and which of its key results and bets point up here. Nothing is written to their repos.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse, parseDocument } from "yaml";
+import { isDone } from "../lib/project.js";
+import { storyMapOf } from "../commands/map.js";
+import { delivery, describeDelivery } from "./delivery.js";
+import { progress, isStale } from "./krs.js";
+import { betIds, krIds, loadBet, loadKr, today } from "./model.js";
+import { git, ignoreCache, readLock, repoEntry, upstreamEntries } from "./upstream.js";
+const MAX_DEPTH = 6;
+const cache = (root) => join(root, ".nikos", "downstream");
+const copyOf = (root, repo) => join(cache(root), ...repo.split("/"));
+const indexOf = (root) => join(cache(root), "index.json");
+/** This repo's path on its host, from the origin remote: owner/repo, or group/subgroup/project. */
+export function ownRepo(root) {
+    const url = spawnSync("git", ["remote", "get-url", "origin"], { cwd: root, encoding: "utf8" }).stdout?.trim() ?? "";
+    const m = url.match(/^(?:[a-z+]+:\/\/[^/]+\/|[^@\s]+@[^:\s]+:)(.+?)(?:\.git)?\/?$/);
+    return m?.[1];
+}
+/** The plans a repo (or a copy of one) lists in planning/downstream.yaml. */
+export function downstreamEntries(dir) {
+    const p = join(dir, "planning", "downstream.yaml");
+    if (!existsSync(p))
+        return [];
+    const list = parse(readFileSync(p, "utf8")) ?? [];
+    if (!Array.isArray(list))
+        throw new Error("planning/downstream.yaml should be a list of { name, repo }");
+    return list.map((e) => {
+        const name = typeof e === "string" ? e : String(e?.name ?? e?.repo ?? "");
+        if (!name)
+            throw new Error("planning/downstream.yaml: each entry needs a name or a repo");
+        return { name, ...(e?.repo ? { entry: repoEntry(e, "planning/downstream.yaml") } : {}) };
+    });
+}
+/** What a copy of a downstream plan says about itself. */
+function read(root, dir, repo, self) {
+    const ups = (() => {
+        try {
+            return upstreamEntries(dir).map((u) => u.repo);
+        }
+        catch {
+            return [];
+        }
+    })();
+    // Joined means it names this repo, or (when this repo's path isn't known) any plan at all.
+    const joined = self ? ups.includes(self) : ups.length > 0;
+    const lock = readLock(dir).find((l) => (self ? l.repo === self : !l.via));
+    const head = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).stdout?.trim();
+    let deliv;
+    if (existsSync(join(dir, "intent", "storymap.yaml"))) {
+        try {
+            const map = storyMapOf(dir);
+            const stories = map.releases.flatMap((r) => r.stories).filter((s) => s.status !== "cancelled");
+            deliv = {
+                stories: stories.length,
+                done: stories.filter((s) => isDone(s.status)).length,
+                approved: stories.filter((s) => s.status === "approved").length,
+                inProgress: stories.filter((s) => s.status === "in_progress").length,
+                releases: map.releases.length,
+            };
+        }
+        catch {
+            // A story map that doesn't read is the team's to fix; the rest of the rollout still shows.
+        }
+    }
+    const krs = krIds(dir).flatMap((id) => {
+        try {
+            const k = loadKr(dir, id).data;
+            return [{ id, title: k.title, ...(k.aligns_to ? { aligns_to: k.aligns_to } : {}), progress: progress(k), stale: isStale(k) }];
+        }
+        catch {
+            return [];
+        }
+    });
+    const bets = betIds(dir).flatMap((id) => {
+        try {
+            const m = loadBet(dir, id).meta;
+            return [{ id, outcome: m.outcome, delivery: describeDelivery(delivery(dir, id)), krs: [m.krs?.primary, ...(m.krs?.also ?? [])].filter(Boolean) }];
+        }
+        catch {
+            return [];
+        }
+    });
+    return {
+        repo,
+        state: joined ? "joined" : "not joined",
+        ...(joined ? {} : { reason: `its planning/upstream.yaml doesn't list ${self ?? "a plan"} yet` }),
+        ...(lock ? { synced: { on: lock.synced, commit: lock.commit, ...(head && self ? { current: lock.commit === head } : {}) } } : {}),
+        ...(deliv ? { delivery: deliv } : {}),
+        krs,
+        bets,
+    };
+}
+/**
+ * The plans below this one, at every level down. Fetches each read-only unless offline, when it
+ * reads the copies already on disk. Unreachable ones are reported, never fatal.
+ */
+export function rollout(root, opts = {}) {
+    const self = opts.as ?? ownRepo(root);
+    const index = existsSync(indexOf(root)) ? JSON.parse(readFileSync(indexOf(root), "utf8")) : {};
+    const plans = [];
+    const queue = downstreamEntries(root).map((listed) => ({ listed, depth: 1, parent: self ?? "" }));
+    const seen = new Set();
+    while (queue.length) {
+        const { listed, depth, via, parent } = queue.shift();
+        const base = { name: listed.name, ...(via ? { via } : {}), krs: [], bets: [] };
+        if (!listed.entry) {
+            plans.push({ ...base, state: "no repo yet" });
+            continue;
+        }
+        const e = listed.entry;
+        if (seen.has(e.repo))
+            continue;
+        seen.add(e.repo);
+        const dir = copyOf(root, e.repo);
+        if (!opts.offline) {
+            rmSync(dir, { recursive: true, force: true });
+            const clone = git(["clone", "--quiet", "--depth", "1", "--branch", e.ref, e.url, dir]);
+            if (clone.status !== 0) {
+                rmSync(dir, { recursive: true, force: true });
+                delete index[e.repo];
+                plans.push({ ...base, repo: e.repo, state: "unreachable", reason: (clone.stderr || "clone failed").trim().split("\n").pop() });
+                continue;
+            }
+            index[e.repo] = { commit: git(["rev-parse", "HEAD"], dir).stdout.trim(), fetched: today() };
+            rmSync(join(dir, ".git"), { recursive: true, force: true }); // a plain copy: nothing to push back
+        }
+        else if (!existsSync(dir)) {
+            plans.push({ ...base, repo: e.repo, state: "unreachable", reason: "not fetched yet: run nikos planning rollout" });
+            continue;
+        }
+        // A plan further down joins the one that listed it, not this repo.
+        const plan = { ...base, ...read(root, dir, e.repo, depth === 1 ? self : parent), ...(index[e.repo] ? { fetched: index[e.repo].fetched } : {}) };
+        if (depth > 1 && plan.synced)
+            delete plan.synced.current;
+        plans.push(plan);
+        if (depth >= MAX_DEPTH)
+            continue;
+        try {
+            for (const below of downstreamEntries(dir))
+                queue.push({ listed: below, depth: depth + 1, via: e.repo, parent: e.repo });
+        }
+        catch (err) {
+            plans.push({ name: `${e.repo}'s downstream.yaml`, state: "unreachable", reason: err.message, krs: [], bets: [] });
+        }
+    }
+    if (!opts.offline) {
+        ignoreCache(root);
+        mkdirSync(cache(root), { recursive: true });
+        writeFileSync(indexOf(root), JSON.stringify(index, null, 2));
+    }
+    return { ...(self ? { repo: self } : {}), plans };
+}
+/** The rollout as lines, one block per plan. */
+export function formatRollout(r) {
+    if (!r.plans.length)
+        return "No plans below this one: list departments and teams in planning/downstream.yaml as `- name: Payments` and `repo: acme/payments-plan`.";
+    const out = [];
+    const joined = r.plans.filter((p) => p.state === "joined").length;
+    out.push(`${joined} of ${r.plans.length} plans below ${r.repo ?? "this one"} have joined.`);
+    for (const p of r.plans) {
+        const mark = p.state === "joined" ? "✓" : p.state === "not joined" ? "!" : "?";
+        out.push(`\n${mark} ${p.name}${p.repo && p.repo !== p.name ? ` (${p.repo})` : ""}${p.via ? `, below ${p.via}` : ""}: ${p.state}${p.reason ? `, ${p.reason}` : ""}`);
+        if (p.synced)
+            out.push(`    synced on ${p.synced.on} at ${p.synced.commit.slice(0, 7)}${p.synced.current === false ? ", behind this plan: ask them to run nikos planning sync" : ""}`);
+        if (p.delivery)
+            out.push(`    delivery: ${p.delivery.done} of ${p.delivery.stories} stories done${p.delivery.approved ? ` (${p.delivery.approved} approved)` : ""}, ${p.delivery.inProgress} in progress`);
+        for (const k of p.krs)
+            out.push(`    KR ${k.id}: ${k.title}, ${Math.round(k.progress * 100)}%${k.stale ? ", stale" : ""}${k.aligns_to ? ` → ${k.aligns_to}` : ""}`);
+        for (const b of p.bets)
+            out.push(`    bet ${b.id}: ${b.delivery}, ${b.outcome}${b.krs.length ? ` → ${b.krs.join(", ")}` : ""}`);
+    }
+    return out.join("\n");
+}
+/** List a department or team in planning/downstream.yaml, or give an entry already there its repo. */
+export function addDownstream(root, input) {
+    const name = input.name?.trim();
+    if (!name)
+        throw new Error("Give the department's or team's name");
+    const entry = { name, ...(input.repo ? { repo: input.repo } : {}), ...(input.host ? { host: input.host } : {}) };
+    if (input.repo)
+        repoEntry(entry, "planning/downstream.yaml"); // a bad repo path or host fails before anything is written
+    const p = join(root, "planning", "downstream.yaml");
+    const doc = parseDocument(existsSync(p) ? readFileSync(p, "utf8") : "# The departments and teams that plan against this one: name, and their repo once they have one.\n[]\n");
+    if (!doc.contents || !("items" in doc.contents))
+        doc.contents = doc.createNode([]);
+    doc.contents.flow = false;
+    const items = doc.contents.items;
+    const at = items.findIndex((it) => {
+        const v = it?.toJSON?.() ?? it;
+        return (typeof v === "string" ? v : v?.name) === name || (input.repo && v?.repo === input.repo);
+    });
+    if (at >= 0)
+        items[at] = doc.createNode(entry);
+    else
+        items.push(doc.createNode(entry));
+    mkdirSync(join(root, "planning"), { recursive: true });
+    writeFileSync(p, doc.toString({ lineWidth: 0 }));
+    return { name, ...(input.repo ? { repo: input.repo } : {}), added: at < 0 };
+}

package/dist/planning/server.d.ts

@@ -0,0 +1,113 @@
+/** What a custom view can rely on. Keep this in step with VIEW_SCRIPT and the save kinds below. */
+export declare const VIEW_CONTRACT = "# Custom planning views\n\nA custom view is a page at planning/views/<name>.html (lowercase letters, digits and hyphens). It is served at /views/<name>, and the server adds /nikos-view.js and the dashboard token to it.\n\nwindow.nikos.data(): Promise<object>\n  The dashboard data: { project, today, plan, krs, bets, story, upstream, views, problems }.\n  krs[]: id, title, owner, unit, baseline, target, by, latest, latestValue, progress, stale, hash, checkins, upstream.\n  bets[]: id, owner, team, hypothesis, krs, starts, review_on, deadline, confidence, outcome, reviews, body, hash, delivery, releases.\n  upstream[] is read-only: plans synced from other repos. Never save to it.\n\nwindow.nikos.save(kind, payload): Promise<{ wrote: string }>\n  \"checkin\": { id, expect, value, note?, evidence? }\n  \"bet\": { id, expect, fields: { owner?, team?, hypothesis?, starts?, review_on?, deadline?, confidence?, dependencies?, outcome? } }\n  \"review\": { id, expect, decision: \"continue\" | \"change\" | \"stop\" | \"complete\", reason, outcome?: \"won\" | \"lost\" }\n\nexpect is the hash of the item as data() returned it. A save rejected with status 409 means the file changed on disk: call data() again and apply the change to the new version. Other rejections carry the reason. Saves only ever write inside planning/.\n";
+/** Everything the views need, as JSON. Files that fail to load are listed in `problems`, not thrown. */
+export declare function planningData(root: string): {
+    project: any;
+    today: string;
+    plan: any;
+    krs: {
+        id: any;
+        title: any;
+        objective: any;
+        owner: any;
+        unit: any;
+        baseline: any;
+        target: any;
+        original_target: any;
+        by: any;
+        stale_after_days: any;
+        aligns_to: any;
+        checkins: any;
+        latest: any;
+        latestValue: any;
+        progress: number;
+        stale: boolean;
+        hash: string;
+        file: string;
+        upstream: {
+            ref: string;
+            repo: string;
+            commit: string | null;
+            found: boolean;
+            kr: any;
+            readOnly: boolean;
+        } | null;
+    }[];
+    bets: {
+        id: any;
+        owner: any;
+        team: any;
+        hypothesis: any;
+        krs: {
+            primary: any;
+            also: any;
+        };
+        starts: any;
+        review_on: any;
+        deadline: any;
+        confidence: any;
+        dependencies: any;
+        outcome: any;
+        reviews: any;
+        body: string;
+        hash: string;
+        file: string;
+        delivery: {
+            text: string;
+            status: "Shipped" | "Building" | "Not started";
+            done: number;
+            total: number;
+            stories: {
+                id: string;
+                status: string;
+            }[];
+            releases: number[];
+        };
+        releases: {
+            number: number;
+            title: string;
+            href: string;
+        }[];
+    }[];
+    story: {
+        activities: {
+            id: string;
+            title: string;
+            steps: {
+                id: string;
+                title: string;
+            }[];
+        }[];
+        releases: import("../commands/map.js").MapRelease[];
+        unreleased: import("../commands/map.js").MapStory[];
+    };
+    upstream: {
+        repo: string;
+        commit?: string;
+        krs: any[];
+        bets: any[];
+    }[];
+    downstream: import("./rollout.js").Rollout | null;
+    views: string[];
+    problems: string[];
+};
+/** Write the whole dashboard as one offline HTML file. Warns first when other repos' plans are inside. */
+export declare function exportSnapshot(root: string, file: string): {
+    wrote: string;
+    warned: boolean;
+};
+export interface RunningServer {
+    url: string;
+    token: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** Start the dashboard on 127.0.0.1 with a fresh token. The url carries the token for the browser. */
+export declare function startServer(root: string, opts?: {
+    port?: number;
+}): Promise<RunningServer>;
+/** `nikos planning serve`: run the dashboard until Ctrl+C, or export it to one file. */
+export declare function runServe(root: string, opts?: {
+    port?: number;
+    exportTo?: string;
+}): Promise<number>;

package/dist/planning/server.js

@@ -12,6 +12,7 @@ import { editBet, reviewBet } from "./bets.js";
 import { delivery, describeDelivery } from "./delivery.js";
 import { checkIn, isStale, latest, progress } from "./krs.js";
 import { betIds, krIds, loadBet, loadKr, loadPlan, paths, StaleError, today } from "./model.js";
+import { rollout } from "./rollout.js";
 import { loadUpstream } from "./upstream.js";
 import { renderDashboard } from "./ui.js";
 const MAX_BODY = 100_000;
@@ -170,6 +171,8 @@ export function planningData(root) {
         bets,
         story: { activities: story.activities, releases: story.releases, unreleased: story.unreleased },
         upstream,
+        // The plans below this one, from the copies the last rollout fetched: loading never fetches.
+        downstream: existsSync(join(root, "planning", "downstream.yaml")) ? rollout(root, { offline: true }) : null,
         views,
         problems,
     };
@@ -177,13 +180,13 @@ export function planningData(root) {
 /** Write the whole dashboard as one offline HTML file. Warns first when other repos' plans are inside. */
 export function exportSnapshot(root, file) {
     const out = resolve(file);
-    const upstream = loadUpstream(root);
-    const warned = upstream.length > 0;
+    const data = planningData(root);
+    const names = [...loadUpstream(root).map((u) => u.repo), ...(data.downstream?.plans ?? []).filter((p) => p.repo && p.state !== "unreachable").map((p) => p.repo)];
+    const warned = names.length > 0;
     if (warned) {
-        const names = upstream.map((u) => u.repo).join(", ");
-        process.stderr.write(`! This snapshot includes plans from other repos (${names}); share it only with people allowed to see them.\n`);
+        process.stderr.write(`! This snapshot includes plans from other repos (${names.join(", ")}); share it only with people allowed to see them.\n`);
     }
-    writeFileSync(out, renderDashboard({ data: planningData(root), readOnly: true }));
+    writeFileSync(out, renderDashboard({ data, readOnly: true }));
     return { wrote: out, warned };
 }
 /** Start the dashboard on 127.0.0.1 with a fresh token. The url carries the token for the browser. */
@@ -253,7 +256,7 @@ function serveGet(root, token, path, res) {
     if (path === "/api/data")
         return send(res, 200, planningData(root));
     if (path === "/map")
-        return send(res, 200, renderMap(root), HTML);
+        return send(res, 200, renderMap(root, { live: true }), HTML);
     if (path === "/nikos-view.js")
         return send(res, 200, VIEW_SCRIPT, JS);
     const m = /^\/views\/([^/]+)$/.exec(path);

package/dist/planning/ui.d.ts

@@ -0,0 +1,7 @@
+export interface DashboardOptions {
+    data: any;
+    token?: string;
+    readOnly: boolean;
+}
+/** The whole dashboard as one HTML page. Read-only renders carry no save code and no token. */
+export declare function renderDashboard({ data, token, readOnly }: DashboardOptions): string;

package/dist/planning/ui.js

@@ -129,6 +129,7 @@ function render() {
   else if (p[0] === 'bets') html = betsView();
   else if (p[0] === 'timeline') html = timelineView();
   else if (p[0] === 'guide') html = guideView();
+  else if (p[0] === 'rollout') html = rolloutView();
   else html = krsView();
   main.innerHTML = (D.problems && D.problems.length ? '<div class="notice">Some planning files could not be read: ' + esc(D.problems.join('; ')) + '</div>' : '') + html;
 }
@@ -176,6 +177,30 @@ function guideView() {
     '<h2 style="margin:20px 0 10px">What nikOS adds</h2><div class="cards">' + value + '</div>';
 }
 
+function rolloutView() {
+  var r = D.downstream;
+  if (!r || !r.plans.length) return '<h1>Rollout</h1><p class="muted">No plans below this one yet. List departments and teams in planning/downstream.yaml.</p>';
+  var joined = r.plans.filter(function (p) { return p.state === 'joined'; }).length;
+  var cls = { 'joined': 'green', 'not joined': 'amber', 'unreachable': '', 'no repo yet': '' };
+  var cards = r.plans.map(function (p) {
+    var rows = [];
+    if (p.synced) rows.push('Synced ' + esc(p.synced.on) + (p.synced.current === false ? ', behind this plan' : ''));
+    else if (p.state === 'joined') rows.push('Not synced yet');
+    if (p.delivery) {
+      var pct = p.delivery.stories ? Math.round(p.delivery.done / p.delivery.stories * 100) : 0;
+      rows.push(esc(p.delivery.done) + ' of ' + esc(p.delivery.stories) + ' stories done' + (p.delivery.approved ? ', ' + esc(p.delivery.approved) + ' approved' : '') + '<div class="progress"><div style="width:' + pct + '%"></div></div>');
+    }
+    var refs = p.krs.map(function (k) { return '<li>KR ' + esc(k.title) + ', ' + Math.round(k.progress * 100) + '%' + (k.stale ? ' ' + chip('Stale', 'amber') : '') + (k.aligns_to ? ' <span class="muted">→ ' + esc(k.aligns_to) + '</span>' : '') + '</li>'; })
+      .concat(p.bets.map(function (b) { return '<li>Bet ' + esc(b.id) + ', ' + esc(b.delivery) + (b.krs.length ? ' <span class="muted">→ ' + esc(b.krs.join(', ')) + '</span>' : '') + '</li>'; }));
+    return '<div class="card"><div class="row"><strong>' + esc(p.name) + '</strong>' + chip(p.state, cls[p.state] || '') + '</div>' +
+      '<div class="muted">' + esc(p.repo || 'no repo yet') + (p.via ? ' · below ' + esc(p.via) : '') + (p.fetched ? ' · read ' + esc(p.fetched) : '') + '</div>' +
+      (p.reason ? '<div class="muted" style="margin-top:6px">' + esc(p.reason) + '</div>' : '') +
+      rows.map(function (x) { return '<div style="margin-top:8px">' + x + '</div>'; }).join('') +
+      (refs.length ? '<ul class="checkins" style="margin-top:8px">' + refs.join('') + '</ul>' : '') + '</div>';
+  }).join('');
+  return '<h1>Rollout</h1><p class="muted">' + joined + ' of ' + r.plans.length + ' plans below this one have joined. Read from copies fetched by nikos planning rollout.</p><div class="cards">' + cards + '</div>';
+}
+
 function krCard(k) {
   var chips = '';
   if (k.stale) chips += chip('Stale', 'amber');
@@ -403,7 +428,7 @@ main.addEventListener('click', function (e) {
 export function renderDashboard({ data, token, readOnly }) {
     const live = !readOnly;
     const json = JSON.stringify(data).replace(/[<\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
-    const nav = `<a data-nav="krs" href="#/krs">Key results</a><a data-nav="bets" href="#/bets">Bets</a><a data-nav="timeline" href="#/timeline">Timeline</a><a data-nav="guide" href="#/guide">How it works</a>`;
+    const nav = `<a data-nav="krs" href="#/krs">Key results</a><a data-nav="bets" href="#/bets">Bets</a><a data-nav="timeline" href="#/timeline">Timeline</a>${data.downstream ? `<a data-nav="rollout" href="#/rollout">Rollout</a>` : ""}<a data-nav="guide" href="#/guide">How it works</a>`;
     // The link out appears only in the served dashboard: an export is a closed file with no outside links.
     const links = live
         ? `<div class="links"><a href="https://www.nikovijay.com/connect?from=nikos-planning" target="_blank" rel="noopener">Made by Niko Vijay</a></div>\n`

package/dist/planning/upstream.d.ts

@@ -0,0 +1,73 @@
+export interface UpstreamEntry {
+    /** The repo's path on its host: owner/repo, or group/subgroup/project. */
+    repo: string;
+    ref: string;
+    url: string;
+}
+export interface LockEntry {
+    repo: string;
+    ref: string;
+    commit: string;
+    synced: string;
+    /** For a plan further up the chain: the upstream that named it. */
+    via?: string;
+}
+export declare const git: (args: string[], cwd?: string) => import("child_process").SpawnSyncReturns<string>;
+/**
+ * The upstream plans listed in planning/upstream.yaml. A repo is its path on the host; the url is
+ * https://<host>/<repo>.git, with host github.com unless the entry names one (gitlab.com, or a
+ * self-managed host), and url: overrides it for anything else.
+ */
+export declare function upstreamEntries(root: string): UpstreamEntry[];
+/** Check one { repo, ref, host, url } entry from a plan's yaml list, and work out its url. */
+export declare function repoEntry(e: any, file: string): UpstreamEntry;
+export declare function readLock(root: string): LockEntry[];
+/** Make sure .nikos/ is gitignored, so upstream copies are never committed. */
+export declare function ignoreCache(root: string): void;
+export interface SyncReport {
+    synced: LockEntry[];
+    unresolved: {
+        repo: string;
+        reason: string;
+    }[];
+}
+/**
+ * Fetch every upstream plan read-only, and the plans above those: a team that names its
+ * department also gets the department's company, so settings and plans reach every level.
+ * Unreachable ones are reported, never fatal.
+ */
+export declare function sync(root: string): SyncReport;
+/** Compare each locked commit with the upstream's current one. */
+export declare function checkStale(root: string): {
+    stale: {
+        repo: string;
+        locked: string;
+        current: string;
+    }[];
+    unresolved: {
+        repo: string;
+        reason: string;
+    }[];
+};
+/** The read-only copies on disk: each upstream's key results and bets. */
+export declare function loadUpstream(root: string): {
+    repo: string;
+    commit?: string;
+    krs: any[];
+    bets: any[];
+}[];
+/** Find owner/repo#id among the synced copies. */
+export declare function resolveRef(root: string, ref: string): {
+    repo: string;
+    kind: "kr" | "bet";
+    data: any;
+} | undefined;
+/** Every owner/repo#id this repo's planning files and story map name, with whether it resolves. */
+export declare function crossRefs(root: string): {
+    ref: string;
+    file: string;
+    resolved: boolean;
+}[];
+export declare function runSync(root: string, opts?: {
+    check?: boolean;
+}): Promise<number>;

package/dist/planning/upstream.js

@@ -1,17 +1,24 @@
 // Plans this repo works toward, in other repos. planning/upstream.yaml lists them;
-// `nikos planning sync` fetches a read-only copy of each into .nikos/upstream/<owner>/<repo>/
+// `nikos planning sync` fetches a read-only copy of each into .nikos/upstream/<repo path>/
 // (gitignored) and records the commit it read in planning/upstream.lock. This repo only ever
-// stores references like owner/repo#id, never the upstream content.
+// stores references like owner/repo#id, never the upstream content. Any git host works:
+// GitHub by default, GitLab (with nested groups) or a self-managed host through `host:`, and
+// anything else through `url:`.
 import { spawnSync } from "node:child_process";
-import { appendFileSync, existsSync, readFileSync, rmSync } from "node:fs";
+import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { basename, join } from "node:path";
 import { parse, stringify } from "yaml";
-import { CROSS_REF } from "../lib/bets.js";
+import { CROSS_REF, REPO_PATH } from "../lib/bets.js";
 import { parseFrontMatter } from "../lib/frontmatter.js";
 import { walk } from "../lib/project.js";
 import { betIds, krIds, loadBet, loadKr, paths, today, writePlanning } from "./model.js";
-const git = (args, cwd) => spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
-/** The upstream plans listed in planning/upstream.yaml. A repo is owner/repo; url defaults to GitHub. */
+export const git = (args, cwd) => spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+const HOST = /^[A-Za-z0-9.-]+(:[0-9]+)?$/;
+/**
+ * The upstream plans listed in planning/upstream.yaml. A repo is its path on the host; the url is
+ * https://<host>/<repo>.git, with host github.com unless the entry names one (gitlab.com, or a
+ * self-managed host), and url: overrides it for anything else.
+ */
 export function upstreamEntries(root) {
     const p = paths(root).upstream;
     if (!existsSync(p))
@@ -19,11 +26,16 @@ export function upstreamEntries(root) {
     const list = parse(readFileSync(p, "utf8")) ?? [];
     if (!Array.isArray(list))
         throw new Error("planning/upstream.yaml should be a list of { repo, ref }");
-    return list.map((e) => {
-        if (typeof e?.repo !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(e.repo))
-            throw new Error(`planning/upstream.yaml: '${e?.repo}' is not owner/repo`);
-        return { repo: e.repo, ref: e.ref ?? "main", url: e.url ?? `https://github.com/${e.repo}.git` };
-    });
+    return list.map((e) => repoEntry(e, "planning/upstream.yaml"));
+}
+/** Check one { repo, ref, host, url } entry from a plan's yaml list, and work out its url. */
+export function repoEntry(e, file) {
+    if (typeof e?.repo !== "string" || !REPO_PATH.test(e.repo)) {
+        throw new Error(`${file}: '${e?.repo}' is not a repo path (owner/repo, or group/subgroup/project on GitLab)`);
+    }
+    if (e.host !== undefined && (typeof e.host !== "string" || !HOST.test(e.host)))
+        throw new Error(`${file}: '${e.host}' is not a host name, e.g. gitlab.com`);
+    return { repo: e.repo, ref: e.ref ?? "main", url: e.url ?? `https://${e.host ?? "github.com"}/${e.repo}.git` };
 }
 export function readLock(root) {
     const p = paths(root).lock;
@@ -31,18 +43,27 @@ export function readLock(root) {
 }
 const cacheDir = (root, repo) => join(paths(root).cache, ...repo.split("/"));
 /** Make sure .nikos/ is gitignored, so upstream copies are never committed. */
-function ignoreCache(root) {
+export function ignoreCache(root) {
     const p = join(root, ".gitignore");
     const text = existsSync(p) ? readFileSync(p, "utf8") : "";
     if (!/^\/?\.nikos\/?$/m.test(text))
         appendFileSync(p, `${text && !text.endsWith("\n") ? "\n" : ""}# nikos planning: read-only copies of upstream plans\n.nikos/\n`);
 }
-/** Fetch every upstream plan read-only. Unreachable ones are reported, never fatal. */
+/** How many levels up sync follows: team → group → department → company, with room to spare. */
+const MAX_DEPTH = 6;
+/**
+ * Fetch every upstream plan read-only, and the plans above those: a team that names its
+ * department also gets the department's company, so settings and plans reach every level.
+ * Unreachable ones are reported, never fatal.
+ */
 export function sync(root) {
     ignoreCache(root);
     const report = { synced: [], unresolved: [] };
     const previous = readLock(root);
-    for (const e of upstreamEntries(root)) {
+    const queue = upstreamEntries(root).map((entry) => ({ entry, depth: 1 }));
+    const seen = new Set(queue.map((q) => q.entry.repo));
+    while (queue.length) {
+        const { entry: e, depth, via } = queue.shift();
         const dir = cacheDir(root, e.repo);
         rmSync(dir, { recursive: true, force: true });
         const clone = git(["clone", "--quiet", "--depth", "1", "--branch", e.ref, e.url, dir]);
@@ -56,14 +77,42 @@ export function sync(root) {
         }
         const commit = git(["rev-parse", "HEAD"], dir).stdout.trim();
         rmSync(join(dir, ".git"), { recursive: true, force: true }); // a plain copy: nothing to push back
-        report.synced.push({ repo: e.repo, ref: e.ref, commit, synced: today() });
+        report.synced.push({ repo: e.repo, ref: e.ref, commit, synced: today(), ...(via ? { via } : {}) });
+        if (depth >= MAX_DEPTH)
+            continue;
+        let above = [];
+        try {
+            above = upstreamEntries(dir);
+        }
+        catch (err) {
+            report.unresolved.push({ repo: `${e.repo}'s upstream.yaml`, reason: err.message });
+        }
+        for (const up of above) {
+            if (seen.has(up.repo))
+                continue;
+            seen.add(up.repo);
+            queue.push({ entry: up, depth: depth + 1, via: e.repo });
+        }
     }
     writePlanning(root, paths(root).lock, `# Written by nikos planning sync: the upstream commit each plan was read at.\n${stringify(report.synced)}`);
     return report;
 }
 /** Compare each locked commit with the upstream's current one. */
 export function checkStale(root) {
-    const entries = upstreamEntries(root);
+    // This repo's own upstreams, and the ones further up that their copies name.
+    const entries = [...upstreamEntries(root)];
+    for (const l of readLock(root)) {
+        if (!REPO_PATH.test(l.repo))
+            continue;
+        try {
+            for (const e of upstreamEntries(cacheDir(root, l.repo)))
+                if (!entries.some((x) => x.repo === e.repo))
+                    entries.push(e);
+        }
+        catch {
+            // A copy with a broken upstream.yaml was reported at sync.
+        }
+    }
     const out = { stale: [], unresolved: [] };
     for (const l of readLock(root)) {
         const e = entries.find((x) => x.repo === l.repo);
@@ -78,13 +127,22 @@ export function checkStale(root) {
     }
     return out;
 }
+/** The repo paths under .nikos/upstream/ that hold a planning/ folder, at any group depth. */
+function copiesOnDisk(cache, prefix = "", depth = 0) {
+    if (depth > 8 || !existsSync(cache))
+        return [];
+    return readdirSync(cache, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name !== "planning")
+        .flatMap((d) => {
+        const path = prefix ? `${prefix}/${d.name}` : d.name;
+        return existsSync(join(cache, d.name, "planning")) ? [path] : copiesOnDisk(join(cache, d.name), path, depth + 1);
+    });
+}
 /** The read-only copies on disk: each upstream's key results and bets. */
 export function loadUpstream(root) {
     const lock = readLock(root);
-    const repos = new Set(lock.map((l) => l.repo));
-    // Also pick up copies whose lock entry is missing (e.g. placed by hand).
-    for (const owner of walk(paths(root).cache).map((p) => p.slice(paths(root).cache.length + 1).split(/[\\/]/).slice(0, 2).join("/")))
-        repos.add(owner);
+    // Locked repos, plus copies whose lock entry is missing (e.g. placed by hand).
+    const repos = new Set([...lock.map((l) => l.repo), ...copiesOnDisk(paths(root).cache)].filter((r) => REPO_PATH.test(r)));
     const out = [];
     for (const repo of repos) {
         const root2 = cacheDir(root, repo);

package/dist/verify/detect.d.ts

@@ -0,0 +1,3 @@
+export type Stack = "js" | "ts" | "python";
+/** Pick the Cucumber runner's stack from the files at the repo root. Undefined means ask the person. */
+export declare function detectStack(root: string): Stack | undefined;