@medicine-wheel/developer-repository-mapping 0.0.0-stage → 0.22.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @medicine-wheel/developer-repository-mapping
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Repository mapping for the Medicine Wheel Developer Suite: an owner says what each of
+their repositories is, in rows tools can read, and one hub reads the others.
+
+Each owner keeps a folder in the repository named after them:
+
+```
+<owner>/<owner>/.miadi/repository-mapping/
+  manifest.json        what the folder is: owner, hub, kind (owner | meta)
+  repositories.jsonl   lifecycle, purpose and horizon in ≤ 55 words, fields, prototypes, git reading
+  features.jsonl       features observed in a repository (a prototype's three core ones)
+  capabilities.jsonl   platform capabilities (usually in the meta hub)
+  relations.jsonl      forked-from, grew-into, consumes, provides, realizes, field-aligns-with
+  owners.jsonl         meta hub only: the hubs it reads
+```
+
+Every row says who wrote it, when, from what evidence, and whether a person has read it
+since. A row a model writes starts `pending`.
+
+## Install
+
+```bash
+npm install -g @medicine-wheel/developer-repository-mapping   # for the mw-repomap CLI
+npm install @medicine-wheel/developer-repository-mapping      # for the library
+```
+
+Node 19 or later. Depends on `@medicine-wheel/ontology-core`, `@medicine-wheel/capabilities` and `zod`.
+
+## mw-repomap
+
+```bash
+mw-repomap init jgwill --owner jgwill --meta          # an empty folder in the jgwill/jgwill clone
+mw-repomap observe ~/repos/jgwill/*                    # git readings, one JSON line per clone
+mw-repomap observe ~/repos/jgwill/* --dir jgwill --write   # store them on the repository rows
+mw-repomap validate jgwill                             # severity file:line node — message; exit 1 on errors
+mw-repomap list jgwill --lifecycle prototype --drift drifted
+mw-repomap show jgwill/smcraft jgwill
+mw-repomap move jgwill/smcraft concretize jgwill --by Guillaume --grounding jgwill/smcraft#12
+mw-repomap hub jgwill                                  # every registered hub, read or not
+mw-repomap serve jgwill                                # http://127.0.0.1:3967/
+mw-repomap wheel jgwill                                # the mapping as wheel nodes and edges
+```
+
+A meta hub reads every hub it registers (from a local path, or from GitHub by default)
+unless `--local`. `observe --write` and `move` refuse to rewrite a folder while any row
+fails to parse. Exit codes: 0 done, 1 errors or a failed read, 2 usage error.
+
+## Library
+
+```ts
+import { checkMapping, mergeMappings, reconcileLifecycle, transition, toWheelNodes } from '@medicine-wheel/developer-repository-mapping';
+import { readHub, readActivity, createMappingServer } from '@medicine-wheel/developer-repository-mapping/node';
+```
+
+The main entry is pure: ids, schemas, the lifecycle state machine (`transition`), activity
+and drift (`classifyActivity`, `reconcileLifecycle`), JSONL parsing that reports bad lines
+by number, `checkMapping`, the meta mapping (`mergeMappings`), `summarize`, and the
+projection into the wheel (`toWheelNodes`, `toWheelEdges`). `./node` holds file, git and
+HTTP access.
+
+## Lifecycle
+
+`unclassified` → `explore` → `prototype` → `concretize` → `implementation` → `release` →
+`maintained`, `archive` from any of them, `reopen` back to `unclassified`. How recently
+anyone committed is read from git separately and compared with the declared lifecycle:
+`converged`, `drifted`, `unobserved` or `undeclared`. Drift is reported, never corrected.
+
+Spec, drawings and relational context: [`rispecs/developer-suite/repository-mapping/`](https://github.com/jgwill/medicine-wheel/tree/main/rispecs/developer-suite/repository-mapping).

package/dist/check.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What a mapping says about itself once its rows are read: duplicates, rows
+ * in the wrong hub, features of a repository the mapping does not hold, and
+ * references to nodes it does not hold.
+ *
+ * A reference to a node the mapping does not hold is a warning, not an
+ * error. A fork's origin lives in someone else's hub, and the platform's
+ * capabilities live in the meta hub; a merged reading resolves them.
+ */
+import { type MappingIssue, type RepositoryMapping } from './types';
+export interface CheckOptions {
+    /** A merged reading of several hubs: rows from many owners are expected. */
+    merged?: boolean;
+}
+export declare function relationKey(row: {
+    from: string;
+    type: string;
+    to: string;
+}): string;
+/**
+ * Whose word a relation is: the owner of the repository (or of the feature's
+ * repository) it starts from. `undefined` for a relation from a service, which
+ * only the meta hub speaks for.
+ */
+export declare function speakingOwner(from: string): string | undefined;
+export declare function checkMapping(mapping: RepositoryMapping, options?: CheckOptions): MappingIssue[];
+export declare function hasErrors(issues: readonly MappingIssue[]): boolean;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA2B,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE7F,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG9D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,GAAE,YAAiB,GAAG,YAAY,EAAE,CAoFnG;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAElE"}

package/dist/check.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * What a mapping says about itself once its rows are read: duplicates, rows
+ * in the wrong hub, features of a repository the mapping does not hold, and
+ * references to nodes it does not hold.
+ *
+ * A reference to a node the mapping does not hold is a warning, not an
+ * error. A fork's origin lives in someone else's hub, and the platform's
+ * capabilities live in the meta hub; a merged reading resolves them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relationKey = relationKey;
+exports.speakingOwner = speakingOwner;
+exports.checkMapping = checkMapping;
+exports.hasErrors = hasErrors;
+const ids_1 = require("./ids");
+const types_1 = require("./types");
+function relationKey(row) {
+    return `${row.from} ${row.type} ${row.to}`;
+}
+/**
+ * Whose word a relation is: the owner of the repository (or of the feature's
+ * repository) it starts from. `undefined` for a relation from a service, which
+ * only the meta hub speaks for.
+ */
+function speakingOwner(from) {
+    const repo = from.startsWith('feature:') ? (0, ids_1.featureRepository)(from) : from;
+    return repo ? (0, ids_1.parseRepositoryNodeId)(repo)?.owner : undefined;
+}
+function checkMapping(mapping, options = {}) {
+    const issues = [];
+    const { manifest } = mapping;
+    const error = (message, nodeId, file) => issues.push({ severity: 'error', message, ...(nodeId ? { nodeId } : {}), ...(file ? { file } : {}) });
+    const warning = (message, nodeId, file) => issues.push({ severity: 'warning', message, ...(nodeId ? { nodeId } : {}), ...(file ? { file } : {}) });
+    // GitHub names are case-insensitive: jgwill/Miadi and jgwill/miadi are one repository.
+    const held = new Set();
+    const heldFolded = new Set();
+    const holdOnce = (id, file) => {
+        if (heldFolded.has(id.toLowerCase()))
+            error(`${id} appears more than once`, id, file);
+        held.add(id);
+        heldFolded.add(id.toLowerCase());
+    };
+    mapping.repositories.forEach((r) => holdOnce(r.nodeId, 'repositories.jsonl'));
+    mapping.features.forEach((f) => holdOnce(f.nodeId, 'features.jsonl'));
+    mapping.capabilities.forEach((c) => holdOnce(c.nodeId, 'capabilities.jsonl'));
+    const repositories = new Map(mapping.repositories.map((r) => [r.nodeId, r]));
+    if (!options.merged) {
+        for (const r of mapping.repositories) {
+            const owner = (0, ids_1.parseRepositoryNodeId)(r.nodeId)?.owner;
+            if (owner && owner.toLowerCase() !== manifest.owner.toLowerCase()) {
+                error(`${r.nodeId} belongs in ${owner}/${owner}'s mapping, not ${manifest.hub}'s`, r.nodeId, 'repositories.jsonl');
+            }
+        }
+        if (manifest.kind === 'owner' && mapping.owners.length) {
+            error(`only a meta hub registers owners; ${manifest.hub} is an owner hub`, undefined, 'owners.jsonl');
+        }
+        for (const rel of mapping.relations) {
+            const owner = speakingOwner(rel.from);
+            if (owner && owner.toLowerCase() !== manifest.owner.toLowerCase()) {
+                error(`${relationKey(rel)} speaks for ${owner}'s ${rel.from}; it belongs in ${owner}/${owner}'s mapping`, rel.from, 'relations.jsonl');
+            }
+        }
+    }
+    const featureCount = new Map();
+    for (const f of mapping.features) {
+        if (!repositories.has(f.repository)) {
+            error(`${f.nodeId} is a feature of ${f.repository}, which this mapping does not hold`, f.nodeId, 'features.jsonl');
+        }
+        featureCount.set(f.repository, (featureCount.get(f.repository) ?? 0) + 1);
+        if (f.realizes && !held.has(f.realizes)) {
+            warning(`${f.nodeId} realizes ${f.realizes}, which this mapping does not hold`, f.nodeId, 'features.jsonl');
+        }
+    }
+    for (const [repo, count] of featureCount) {
+        if (repositories.get(repo)?.lifecycle === 'prototype' && count > types_1.PROTOTYPE_CORE_FEATURES) {
+            warning(`${repo} is a prototype with ${count} features; name its ${types_1.PROTOTYPE_CORE_FEATURES} core ones`, repo, 'features.jsonl');
+        }
+    }
+    for (const c of mapping.capabilities) {
+        for (const provider of c.providedBy) {
+            if (provider.startsWith('repository:') && !held.has(provider)) {
+                warning(`${c.nodeId} is provided by ${provider}, which this mapping does not hold`, c.nodeId, 'capabilities.jsonl');
+            }
+        }
+    }
+    const relations = new Set();
+    for (const rel of mapping.relations) {
+        const key = relationKey(rel);
+        if (relations.has(key))
+            error(`${key} appears more than once`, rel.from, 'relations.jsonl');
+        relations.add(key);
+        for (const end of [rel.from, rel.to]) {
+            const kind = end.slice(0, end.indexOf(':'));
+            if ((kind === 'repository' || kind === 'feature' || kind === 'capability') && !held.has(end)) {
+                warning(`${key}: ${end} is not in this mapping`, rel.from, 'relations.jsonl');
+            }
+        }
+    }
+    const hubs = new Set();
+    for (const o of mapping.owners) {
+        if (hubs.has(o.hub))
+            error(`${o.hub} is registered more than once`, undefined, 'owners.jsonl');
+        hubs.add(o.hub);
+    }
+    return issues;
+}
+function hasErrors(issues) {
+    return issues.some((i) => i.severity === 'error');
+}
+//# sourceMappingURL=check.js.map

package/dist/check.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * mw-repomap — make, check, observe and serve a repository mapping.
+ *
+ *   mw-repomap init [<hub-dir>] --owner <login> [--meta] [--description <text>]
+ *   mw-repomap validate [<path>] [--local] [--json]
+ *   mw-repomap list [<path>] [--lifecycle <state>] [--drift <drift>] [--revision <state>] [--field <id>] [--local] [--json]
+ *   mw-repomap show <repository> [<path>] [--local] [--json]
+ *   mw-repomap observe <clone>... [--dir <path>] [--by <observer>] [--write]
+ *   mw-repomap move <repository> <event> [<path>] --by <who> [--grounding <evidence>]
+ *   mw-repomap hub [<path>] [--json]
+ *   mw-repomap serve [<path>] [--port <n>] [--host <address>] [--local]
+ *   mw-repomap wheel [<path>] [--local]
+ *
+ * <path> is a mapping folder, or an owner hub clone holding
+ * .miadi/repository-mapping/; the current directory when absent. A meta hub
+ * reads every owner hub it registers, unless --local. <repository> is
+ * owner/name or repository:owner/name.
+ *
+ * `observe --write` and `move` rewrite the folder's JSONL, and refuse while
+ * any row fails to parse: a row that did not parse would not be written back.
+ *
+ * Exit codes: 0 done, 1 the mapping has errors or a read failed, 2 usage error.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/cli.js

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * mw-repomap — make, check, observe and serve a repository mapping.
+ *
+ *   mw-repomap init [<hub-dir>] --owner <login> [--meta] [--description <text>]
+ *   mw-repomap validate [<path>] [--local] [--json]
+ *   mw-repomap list [<path>] [--lifecycle <state>] [--drift <drift>] [--revision <state>] [--field <id>] [--local] [--json]
+ *   mw-repomap show <repository> [<path>] [--local] [--json]
+ *   mw-repomap observe <clone>... [--dir <path>] [--by <observer>] [--write]
+ *   mw-repomap move <repository> <event> [<path>] --by <who> [--grounding <evidence>]
+ *   mw-repomap hub [<path>] [--json]
+ *   mw-repomap serve [<path>] [--port <n>] [--host <address>] [--local]
+ *   mw-repomap wheel [<path>] [--local]
+ *
+ * <path> is a mapping folder, or an owner hub clone holding
+ * .miadi/repository-mapping/; the current directory when absent. A meta hub
+ * reads every owner hub it registers, unless --local. <repository> is
+ * owner/name or repository:owner/name.
+ *
+ * `observe --write` and `move` rewrite the folder's JSONL, and refuse while
+ * any row fails to parse: a row that did not parse would not be written back.
+ *
+ * Exit codes: 0 done, 1 the mapping has errors or a read failed, 2 usage error.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const check_1 = require("./check");
+const ids_1 = require("./ids");
+const lifecycle_1 = require("./lifecycle");
+const schemas_1 = require("./schemas");
+const summary_1 = require("./summary");
+const types_1 = require("./types");
+const wheel_1 = require("./wheel");
+const fs_1 = require("./node/fs");
+const git_1 = require("./node/git");
+const hub_1 = require("./node/hub");
+const server_1 = require("./node/server");
+const USAGE = [
+    'usage: mw-repomap init [<hub-dir>] --owner <login> [--meta] [--description <text>]',
+    '       mw-repomap validate [<path>] [--local] [--json]',
+    '       mw-repomap list [<path>] [--lifecycle <state>] [--drift <drift>] [--revision <state>] [--field <id>] [--local] [--json]',
+    '       mw-repomap show <repository> [<path>] [--local] [--json]',
+    '       mw-repomap observe <clone>... [--dir <path>] [--by <observer>] [--write]',
+    '       mw-repomap move <repository> <event> [<path>] --by <who> [--grounding <evidence>]',
+    '       mw-repomap hub [<path>] [--json]',
+    '       mw-repomap serve [<path>] [--port <n>] [--host <address>] [--local]',
+    '       mw-repomap wheel [<path>] [--local]',
+].join('\n');
+const BOOLEAN_FLAGS = new Set(['meta', 'local', 'json', 'write', 'help']);
+/** The flags each command takes. Any other flag is a usage error, so a misspelling never passes silently. */
+const COMMAND_FLAGS = {
+    init: ['owner', 'meta', 'description'],
+    validate: ['local', 'json'],
+    list: ['lifecycle', 'drift', 'revision', 'field', 'local', 'json'],
+    show: ['local', 'json'],
+    observe: ['dir', 'by', 'write'],
+    move: ['by', 'grounding'],
+    hub: ['json'],
+    serve: ['port', 'host', 'local'],
+    wheel: ['local'],
+};
+class UsageError extends Error {
+}
+function parse(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const key = arg.slice(2);
+        if (BOOLEAN_FLAGS.has(key)) {
+            flags[key] = true;
+            continue;
+        }
+        const value = argv[++i];
+        if (value === undefined || value.startsWith('--'))
+            throw new UsageError(`--${key} needs a value`);
+        flags[key] = value;
+    }
+    const allowed = COMMAND_FLAGS[positional[0]];
+    if (allowed) {
+        const unknown = Object.keys(flags).filter((key) => !allowed.includes(key));
+        if (unknown.length) {
+            throw new UsageError(`${positional[0]} does not take ${unknown.map((k) => `--${k}`).join(', ')}; it takes ${allowed.map((k) => `--${k}`).join(', ') || 'no flags'}`);
+        }
+    }
+    return { positional, flags };
+}
+/** A flag's value, `undefined` when absent. An empty value is a usage error, not an absent flag. */
+const text = (flags, key) => {
+    const value = flags[key];
+    if (typeof value !== 'string')
+        return undefined;
+    if (!value.trim())
+        throw new UsageError(`--${key} needs a value`);
+    return value;
+};
+function printIssues(issues) {
+    for (const i of issues) {
+        const where = `${i.file ?? ''}${i.line ? `:${i.line}` : ''}`;
+        console.error(`${i.severity.padEnd(7)} ${where}${i.nodeId ? ` ${i.nodeId}` : ''} — ${i.message}`);
+    }
+}
+async function mappingDir(arg) {
+    const start = arg ?? process.cwd();
+    const dir = await (0, fs_1.findMappingDir)(start);
+    if (!dir) {
+        throw new Error(`no mapping folder at ${path.resolve(start)} (mw-repomap init --owner <login> makes one)`);
+    }
+    return dir;
+}
+async function hubOrFail(arg, local) {
+    const read = await (0, hub_1.readHub)(await mappingDir(arg), { local });
+    if (!read.merged) {
+        printIssues(read.issues);
+        throw new Error('the manifest could not be read');
+    }
+    return read;
+}
+/** Read the folder for a rewrite; refuse while any row fails to parse. */
+async function forRewrite(dir) {
+    const read = await (0, fs_1.readMappingDir)(dir);
+    if (!read.mapping || (0, check_1.hasErrors)(read.issues)) {
+        printIssues(read.issues);
+        throw new Error('rows fail to parse; fix them before rewriting this folder (mw-repomap validate)');
+    }
+    return read.mapping;
+}
+const defaultObserver = () => `${os.userInfo().username}@${os.hostname()}`;
+async function init(positional, flags) {
+    const owner = text(flags, 'owner');
+    if (!owner)
+        throw new UsageError('init needs --owner <login>');
+    const hubDir = path.resolve(positional[1] ?? process.cwd());
+    const dir = hubDir.endsWith(types_1.MAPPING_DIR) ? hubDir : path.join(hubDir, types_1.MAPPING_DIR);
+    const manifest = schemas_1.MappingManifestSchema.safeParse({
+        schema: types_1.MAPPING_SCHEMA,
+        version: 1,
+        owner,
+        hub: `${owner}/${owner}`,
+        kind: flags.meta ? 'meta' : 'owner',
+        ...(text(flags, 'description') ? { description: text(flags, 'description') } : {}),
+    });
+    if (!manifest.success)
+        throw new UsageError(manifest.error.issues.map((i) => i.message).join('; '));
+    await (0, fs_1.initMappingDir)(dir, manifest.data);
+    console.log(`${manifest.data.kind} hub ${manifest.data.hub}: ${dir}`);
+    return 0;
+}
+async function validate(positional, flags) {
+    const read = await (0, hub_1.readHub)(await mappingDir(positional[1]), { local: flags.local === true });
+    const errors = read.issues.filter((i) => i.severity === 'error').length;
+    const warnings = read.issues.length - errors;
+    if (flags.json) {
+        console.log(JSON.stringify({ errors, warnings, hubs: read.hubs, issues: read.issues }, null, 2));
+    }
+    else {
+        printIssues(read.issues);
+        const m = read.merged;
+        const rows = m ? `${m.repositories.length} repositories, ${m.features.length} features, ${m.capabilities.length} capabilities, ${m.relations.length} relations` : 'nothing read';
+        console.error(`${errors} errors, ${warnings} warnings across ${read.hubs.length} hub(s): ${rows}`);
+    }
+    return errors ? 1 : 0;
+}
+async function list(positional, flags) {
+    const { merged } = await hubOrFail(positional[1], flags.local === true);
+    const readings = new Map((0, summary_1.summarize)(merged).readings.map((r) => [r.nodeId, r]));
+    const rows = merged.repositories.filter((r) => {
+        const reading = readings.get(r.nodeId);
+        return ((!text(flags, 'lifecycle') || r.lifecycle === text(flags, 'lifecycle')) &&
+            (!text(flags, 'drift') || reading?.drift === text(flags, 'drift')) &&
+            (!text(flags, 'revision') || r.revision === text(flags, 'revision')) &&
+            (!text(flags, 'field') || r.fields.includes(text(flags, 'field'))));
+    });
+    if (flags.json) {
+        console.log(JSON.stringify(rows.map((r) => ({ ...r, reading: readings.get(r.nodeId) })), null, 2));
+        return 0;
+    }
+    const width = Math.max(10, ...rows.map((r) => r.nodeId.length - 'repository:'.length));
+    for (const r of rows) {
+        const reading = readings.get(r.nodeId);
+        const git = reading?.activity ? `${reading.activity}${reading.daysSinceLastCommit === undefined ? '' : ` ${reading.daysSinceLastCommit}d`}` : '-';
+        const purpose = r.purpose ? (r.purpose.length > 70 ? `${r.purpose.slice(0, 69)}…` : r.purpose) : `(${r.status})`;
+        console.log([r.nodeId.slice('repository:'.length).padEnd(width), r.lifecycle.padEnd(14), git.padEnd(12), (reading?.drift ?? '').padEnd(10), r.revision.padEnd(8), purpose].join('  '));
+    }
+    console.error(`${rows.length} of ${merged.repositories.length} repositories`);
+    return 0;
+}
+async function show(positional, flags) {
+    const id = positional[1] ? (0, ids_1.toRepositoryNodeId)(positional[1]) : undefined;
+    if (!id)
+        throw new UsageError('show needs a repository: owner/name');
+    const { merged } = await hubOrFail(positional[2], flags.local === true);
+    const repo = merged.repositories.find((r) => r.nodeId.toLowerCase() === id.toLowerCase());
+    if (!repo) {
+        console.error(`mw-repomap: ${id} is not in this mapping`);
+        return 1;
+    }
+    const features = merged.features.filter((f) => f.repository === repo.nodeId);
+    const relations = merged.relations.filter((r) => r.from === repo.nodeId || r.to === repo.nodeId);
+    const reading = (0, lifecycle_1.reconcileLifecycle)(repo);
+    if (flags.json) {
+        console.log(JSON.stringify({ repository: repo, reading, features, relations, source: merged.sources[repo.nodeId] }, null, 2));
+        return 0;
+    }
+    const lines = [
+        `${repo.nodeId}  ${(0, ids_1.repositoryUrl)(repo.nodeId) ?? ''}`,
+        `  ${repo.lifecycle} · ${repo.origin} · purpose ${repo.status} · ${repo.revision}`,
+        `  git: ${reading.reason} (${reading.drift})`,
+        repo.purpose ? `  purpose: ${repo.purpose}` : '',
+        repo.horizon ? `  horizon: ${repo.horizon}` : '',
+        repo.fields.length ? `  fields: ${repo.fields.join(', ')}` : '',
+        repo.prototypes.length ? `  prototypes: ${repo.prototypes.join(', ')}` : '',
+        `  features (${features.length}):`,
+        ...features.map((f) => `    ${f.name} [${f.status}]${f.realizes ? ` → ${f.realizes}` : ''}${f.statement ? `: ${f.statement}` : ''}`),
+        `  relations (${relations.length}):`,
+        ...relations.map((r) => `    ${r.from} ${r.type} ${r.to}`),
+        `  read: ${repo.grounding.join(', ')}`,
+        `  stated by ${repo.statedBy} at ${repo.statedAt}${repo.revisedBy ? `, ${repo.revision} by ${repo.revisedBy} at ${repo.revisedAt}` : ''}`,
+        `  from ${merged.sources[repo.nodeId]}`,
+    ];
+    console.log(lines.filter(Boolean).join('\n'));
+    return 0;
+}
+async function observe(positional, flags) {
+    const clones = positional.slice(1);
+    if (!clones.length)
+        throw new UsageError('observe needs at least one clone');
+    const observedBy = text(flags, 'by') ?? defaultObserver();
+    const dir = flags.write ? await mappingDir(text(flags, 'dir')) : undefined;
+    const mapping = dir ? await forRewrite(dir) : undefined;
+    let failed = 0;
+    let written = 0;
+    for (const clone of clones) {
+        try {
+            const observed = await (0, git_1.readActivity)(path.resolve(clone), { observedBy });
+            const nodeId = await (0, git_1.originRepository)(path.resolve(clone));
+            console.log(JSON.stringify({ clone, nodeId: nodeId ?? null, observed }));
+            if (!mapping)
+                continue;
+            // GitHub names are case-insensitive: a clone of JGWill/miadi is jgwill/Miadi's row.
+            const row = nodeId ? mapping.repositories.find((r) => r.nodeId.toLowerCase() === nodeId.toLowerCase()) : undefined;
+            if (!row) {
+                console.error(`mw-repomap: ${nodeId ?? clone} is not in the mapping yet; reading not written`);
+                continue;
+            }
+            row.observed = observed;
+            written += 1;
+        }
+        catch (error) {
+            failed += 1;
+            console.error(`mw-repomap: ${clone}: ${error.message}`);
+        }
+    }
+    if (dir && mapping) {
+        await (0, fs_1.writeMappingDir)(dir, mapping);
+        console.error(`${written} reading(s) written to ${dir}`);
+    }
+    return failed ? 1 : 0;
+}
+async function move(positional, flags) {
+    const id = positional[1] ? (0, ids_1.toRepositoryNodeId)(positional[1]) : undefined;
+    const event = schemas_1.LifecycleEventSchema.safeParse(positional[2]);
+    const by = text(flags, 'by');
+    if (!id || !event.success)
+        throw new UsageError(`move needs a repository and an event: ${schemas_1.LifecycleEventSchema.options.join(', ')}`);
+    if (!by)
+        throw new UsageError('move needs --by <who>: a lifecycle change is a statement someone makes');
+    const dir = await mappingDir(positional[3]);
+    const mapping = await forRewrite(dir);
+    const row = mapping.repositories.find((r) => r.nodeId.toLowerCase() === id.toLowerCase());
+    if (!row) {
+        console.error(`mw-repomap: ${id} is not in ${dir}`);
+        return 1;
+    }
+    const result = (0, lifecycle_1.transition)(row.lifecycle, event.data);
+    if (!result.ok) {
+        console.error(`mw-repomap: ${result.reason}`);
+        return 1;
+    }
+    row.lifecycle = result.to;
+    row.statedBy = by;
+    row.statedAt = new Date().toISOString();
+    row.revision = 'pending';
+    delete row.revisedBy;
+    delete row.revisedAt;
+    const grounding = text(flags, 'grounding');
+    if (grounding && !row.grounding.includes(grounding))
+        row.grounding.push(grounding);
+    await (0, fs_1.writeMappingDir)(dir, mapping);
+    console.log(`${id}: ${result.from} --${result.event}--> ${result.to}`);
+    return 0;
+}
+async function hub(positional, flags) {
+    const read = await hubOrFail(positional[1], false);
+    if (flags.json) {
+        console.log(JSON.stringify({ hubs: read.hubs, summary: (0, summary_1.summarize)(read.merged) }, null, 2));
+    }
+    else {
+        for (const h of read.hubs) {
+            const errors = h.issues.filter((i) => i.severity === 'error').length;
+            console.log(`${h.hub.padEnd(40)} ${h.read ? `${h.repositories} repositories` : 'not read'}  ${errors} errors, ${h.issues.length - errors} warnings  ${h.source}`);
+        }
+    }
+    return read.hubs.some((h) => !h.read) ? 1 : 0;
+}
+async function serve(positional, flags) {
+    const dir = await mappingDir(positional[1]);
+    const port = Number(text(flags, 'port') ?? 3967);
+    const host = text(flags, 'host') ?? '127.0.0.1';
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new UsageError('--port needs a port number');
+    // Bound to loopback, answer only loopback names: a page that rebinds its own
+    // name to 127.0.0.1 is refused. Bound wider, the person chose who reaches it.
+    const loopback = server_1.LOOPBACK_HOSTS.includes(host.toLowerCase()) || host === '::1';
+    const server = (0, server_1.createMappingServer)(() => (0, hub_1.readHub)(dir, { local: flags.local === true }), {
+        ...(loopback ? { allowedHosts: server_1.LOOPBACK_HOSTS } : {}),
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => resolve());
+    });
+    const address = server.address();
+    const shown = typeof address === 'object' && address ? `http://${host}:${address.port}/` : `http://${host}:${port}/`;
+    console.error(`mw-repomap: serving ${dir} at ${shown}`);
+    return new Promise(() => { });
+}
+async function wheel(positional, flags) {
+    const { merged } = await hubOrFail(positional[1], flags.local === true);
+    console.log(JSON.stringify({ nodes: (0, wheel_1.toWheelNodes)(merged), edges: (0, wheel_1.toWheelEdges)(merged) }, null, 2));
+    return 0;
+}
+const COMMANDS = {
+    init,
+    validate,
+    list,
+    show,
+    observe,
+    move,
+    hub,
+    serve,
+    wheel,
+};
+async function main() {
+    const { positional, flags } = parse(process.argv.slice(2));
+    const command = positional[0];
+    if (command === 'help' || (flags.help && !command)) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (!command)
+        throw new UsageError('a command is needed');
+    const run = COMMANDS[command];
+    if (!run)
+        throw new UsageError(`unknown command: ${command}`);
+    return run(positional, flags);
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    if (error instanceof UsageError) {
+        console.error(`mw-repomap: ${error.message}`);
+        console.error(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    console.error(`mw-repomap: ${error.message}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map