unitbob 0.7.8 → 0.7.13

package/dist/files/mapBuild.js

@@ -28,7 +28,7 @@ export function readFreshGraph(projectRoot) {
     parseJson(rawGraphJson, path);
     return rawGraphJson;
 }
-export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath) {
+export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath, existingCapabilities = []) {
     const packet = {
         project_root: projectRoot,
         graph_path: graphPath(projectRoot),
@@ -37,6 +37,7 @@ export function writeMapBuildRequest(projectRoot, recipes, routeInventoryPath) {
         surface_output_path: surfaceOutputPath(projectRoot),
         ...(routeInventoryPath ? { route_inventory_path: routeInventoryPath } : {}),
         recipes,
+        existing_capabilities: existingCapabilities,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });

package/dist/files/suiteBuild.js

@@ -369,12 +369,13 @@ function isRunEvidence(value, digest) {
         typeof run.revision === 'string' && run.revision &&
         typeof run.run_result === 'string' && run.run_result);
 }
-export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }) {
+export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }, excludeFeatureTags = []) {
     const request = {
         project_root: projectRoot,
         output_path: outputPath(projectRoot),
         branches,
         known_defect_context: knownDefectContext,
+        exclude_feature_tags: excludeFeatureTags,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -421,6 +422,9 @@ export function readSuiteBuildRequest(projectRoot) {
     return {
         ...request,
         known_defect_context: readKnownDefectContext(request.known_defect_context, path),
+        exclude_feature_tags: Array.isArray(request.exclude_feature_tags)
+            ? request.exclude_feature_tags.filter((tag) => typeof tag === 'string')
+            : [],
     };
 }
 function readKnownDefectContext(value, path) {
@@ -533,7 +537,10 @@ function readBranch(entry, rootFor, path, projectRoot) {
 // file already under that path is the answer". Re-serializing a whole suite into
 // this JSON on every rebuild was the single largest cost in the build loop, and
 // the copy was never more trustworthy than the file that was actually executed.
-function resolveSuiteFile(file, root, path, suiteKind, projectRoot) {
+//
+// Exported for a feature's answer (spec 52-3), which is one branch of the same
+// shape read from its own file.
+export function resolveSuiteFile(file, root, path, suiteKind, projectRoot) {
     if (!file || typeof file !== 'object') {
         throw new Error(`${path}: the ${suiteKind} branch is missing suite_file.`);
     }

package/dist/runner/bdd.js

@@ -56,7 +56,7 @@ const CUCUMBER_LOAD_ORDER = 'Files load in filename order, and the shared file i
 // fourth runner cannot be added with only half of itself stated.
 const BDD_STRATEGIES = {
     cucumber: {
-        run: (projectRoot) => runCucumberRuby(projectRoot),
+        run: (projectRoot, _mainPath, filter) => runCucumberRuby(projectRoot, filter),
         loading: {
             step_files: '*.rb',
             requirements: [
@@ -68,7 +68,7 @@ const BDD_STRATEGIES = {
         },
     },
     'cucumber-js': {
-        run: (projectRoot) => runCucumberJs(projectRoot),
+        run: (projectRoot, _mainPath, filter) => runCucumberJs(projectRoot, filter),
         loading: {
             step_files: '*.js',
             requirements: [
@@ -84,7 +84,7 @@ const BDD_STRATEGIES = {
         },
     },
     'pytest-bdd': {
-        run: (projectRoot, mainPath) => runPytestBdd(projectRoot, mainPath),
+        run: (projectRoot, mainPath, filter) => runPytestBdd(projectRoot, mainPath, filter),
         loading: {
             step_files: 'test_*.py',
             requirements: [
@@ -100,12 +100,26 @@ const BDD_STRATEGIES = {
         },
     },
 };
-export function runBddSuite(projectRoot, runner, mainPath) {
+export function runBddSuite(projectRoot, runner, mainPath, filter) {
     const strategy = strategyFor(runner);
     if (!strategy) {
         return Promise.reject(new Error(`Unsupported BDD runner "${runner}" — rebuild the behavioral suite.`));
     }
-    return strategy.run(projectRoot, mainPath);
+    return strategy.run(projectRoot, mainPath, filter);
+}
+// The filter as a tag expression. Both Cucumbers read `@tag`; pytest-bdd turns
+// a tag into a marker of the same name and reads `-m`, where the `@` would be
+// a syntax error. Empty for no filter, so the caller adds no flag at all.
+function tagExpression(filter, prefix) {
+    if (!filter)
+        return '';
+    if ('only' in filter)
+        return `${prefix}${filter.only}`;
+    return filter.exclude.map((tag) => `not ${prefix}${tag}`).join(' and ');
+}
+function tagArgs(filter, flag, prefix) {
+    const expression = tagExpression(filter, prefix);
+    return expression ? [flag, expression] : [];
 }
 // How this runner loads step files, for whoever has to write one. Null for a
 // runner this connector does not run, which is the same answer `runBddSuite`
@@ -122,7 +136,7 @@ function strategyFor(runner) {
 // Ruby: `cucumber` with the built-in message formatter. The features and step
 // definitions both live under the behavioral root; --require points at the step
 // definitions so only the Unitbob bundle loads.
-async function runCucumberRuby(projectRoot) {
+async function runCucumberRuby(projectRoot, filter) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS);
     const sidecarGemfile = join(projectRoot, BEHAVIORAL_GEMFILE);
@@ -130,7 +144,10 @@ async function runCucumberRuby(projectRoot) {
         throw missingRunner('Cucumber');
     }
     const command = 'bundle';
-    const args = ['exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
+    const args = [
+        'exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT,
+        ...tagArgs(filter, '--tags', '@'),
+    ];
     const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
     const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,
@@ -147,7 +164,7 @@ function missingRunner(name) {
 }
 // JS/TS: `@cucumber/cucumber` (cucumber-js) with the message formatter written
 // to a file.
-async function runCucumberJs(projectRoot) {
+async function runCucumberJs(projectRoot, filter) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, STEP_DEFINITIONS, '**', '*');
     const command = `${BEHAVIORAL_ROOT}/node_modules/.bin/cucumber-js`;
@@ -160,6 +177,7 @@ async function runCucumberJs(projectRoot) {
         steps,
         '--format',
         `message:${CUCUMBER_REPORT}`,
+        ...tagArgs(filter, '--tags', '@'),
     ];
     const survivor = clearReport(join(projectRoot, CUCUMBER_REPORT));
     const run = await runInProject(projectRoot, command, args, {
@@ -171,7 +189,7 @@ async function runCucumberJs(projectRoot) {
 // Python: pytest driving pytest-bdd, with the connector's reporter plugin. The
 // plugin writes the JSON report; `-c` isolates the run from the project's own
 // addopts. The runner command is connector-owned.
-async function runPytestBdd(projectRoot, mainPath) {
+async function runPytestBdd(projectRoot, mainPath, filter) {
     mkdirSync(join(projectRoot, BEHAVIORAL_ROOT), { recursive: true });
     writeFileSync(join(projectRoot, PYTEST_INI_FILE), PYTEST_INI);
     writeFileSync(join(projectRoot, PYTEST_BDD_PLUGIN_FILE), PYTEST_BDD_PLUGIN);
@@ -186,7 +204,15 @@ async function runPytestBdd(projectRoot, mainPath) {
     // `--rootdir .`, not the absolute root: the working directory is the project
     // root in every place, and an absolute host path would name a directory that
     // does not exist wherever the run actually happens.
-    const args = ['-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.'];
+    // The marker filter goes after `--rootdir`, so the two arguments the harness
+    // loading depends on keep their place at the end of the unfiltered command.
+    // pytest-bdd hangs a marker named after each tag on the scenario; the
+    // connector's ini registers none, and an unregistered marker is a warning,
+    // not an error (spec 52-3, non-goal).
+    const args = [
+        '-m', 'pytest', '-c', PYTEST_INI_FILE, '-p', 'no:cacheprovider', '-p', pluginModule(), stepsDir, '--rootdir', '.',
+        ...tagArgs(filter, '-m', ''),
+    ];
     const survivor = clearReport(join(projectRoot, PYTEST_BDD_REPORT));
     const run = await runInProject(projectRoot, command, args, {
         timeoutMs: BDD_TIMEOUT_MS,

package/dist/runner/failureDigest.js

@@ -24,6 +24,65 @@ export function reportedFailures(runner, report) {
         return null;
     return extract(runner, report);
 }
+// Spec 52-4, AC 1.10. The same parse, read for a third question: how many of
+// a feature's scenarios passed and how many did not. `put-tests` decides from
+// it which proof to attach — all red is the red run, all green with a review
+// is the review, anything else is no proof — and whether a review may be sent
+// at all. The number reaches a sentence on this machine and the choice of a
+// field; the server checks whatever proof it is sent against the report
+// itself. Only the two behavioral shapes have scenarios to count; a report
+// that cannot be read is no tally, never a green one.
+export function scenarioTally(runner, report) {
+    if (!report.trim())
+        return null;
+    const outcomes = scenarioOutcomes(runner, report);
+    if (outcomes === null)
+        return null;
+    const failed = outcomes.filter((passed) => !passed).length;
+    return { passed: outcomes.length - failed, failed };
+}
+// One entry per scenario, true when it passed. Cucumber emits one
+// `testCaseStarted` per attempt when a scenario is retried, so the rows are
+// keyed by the test case and the last attempt is the one that counts — the
+// one the run ended on.
+function scenarioOutcomes(runner, report) {
+    switch (runner) {
+        case 'cucumber':
+        case 'cucumber-js': {
+            const envelopes = [];
+            for (const line of report.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const parsed = parseObject(line);
+                if (!parsed)
+                    return null;
+                envelopes.push(parsed);
+            }
+            const failedRuns = new Set();
+            for (const envelope of envelopes) {
+                const finished = envelope.testStepFinished;
+                const status = text(finished?.testStepResult?.status);
+                if (finished && status !== 'PASSED' && status !== 'SKIPPED')
+                    failedRuns.add(text(finished.testCaseStartedId));
+            }
+            const lastAttempt = new Map();
+            for (const envelope of envelopes) {
+                const started = envelope.testCaseStarted;
+                if (started)
+                    lastAttempt.set(text(started.testCaseId), text(started.id));
+            }
+            return [...lastAttempt.values()].map((startedId) => !failedRuns.has(startedId));
+        }
+        case 'pytest-bdd': {
+            const data = parseObject(report);
+            if (!Array.isArray(data?.scenarios))
+                return null;
+            return rows(data.scenarios).map((scenario) => text(scenario.status) === 'passed');
+        }
+        default:
+            return null;
+    }
+}
 // One hash for one set. Same set, same hash, on any machine and in any order.
 export function digestOf(failures) {
     return createHash('sha256').update(JSON.stringify(failures)).digest('hex');

package/dist/runner/gitRevision.js

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+// The revision a connector-made run was taken at, for the server's record:
+// `git rev-parse HEAD`, with `-dirty` when the tree has changes, or a word
+// when there is no git to ask. Read by the known-defect probe (the review)
+// and by the proof of red of a feature's checks (spec 52-3), from one place.
+export function gitRevision(projectRoot) {
+    try {
+        const options = {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        const head = execFileSync('git', ['rev-parse', 'HEAD'], options).trim();
+        const dirty = execFileSync('git', ['status', '--porcelain'], options).trim();
+        return dirty ? `${head}-dirty` : head;
+    }
+    catch {
+        return 'working-tree';
+    }
+}

package/dist/runner/manifest.js

@@ -24,7 +24,9 @@ export function withInstalledRunnerVersion(envelope, runner, projectRoot) {
 const BEHAVIORAL_DIR = '.unitbob/behavioral';
 // Matches the server's own PINNED_VERSION: a digit, then version characters.
 const PINNED_VERSION = /^[0-9][0-9A-Za-z.\-+]*$/;
-function installedRunnerVersion(runner, projectRoot) {
+// Exported for a feature's checks (spec 52-3), which take the runner from the
+// main suite rather than from a selection and still owe the server its version.
+export function installedRunnerVersion(runner, projectRoot) {
     const root = join(projectRoot, BEHAVIORAL_DIR);
     const found = readInstalledVersion(runner, root);
     return found && PINNED_VERSION.test(found) ? found : null;

package/dist/runner/outputTail.js

@@ -0,0 +1,13 @@
+// The end of what a run printed, stderr first: enough to see why a runner
+// died, not the whole log. One place for the three verbs that print it
+// (`check`, `run-local`, `put-tests`); `run-local` asks for more because the
+// person is reading it in a loop, `check` files it into a suite error.
+export function outputTail(result, limit) {
+    const bits = [];
+    if (result.stderr.trim())
+        bits.push(result.stderr.trim());
+    if (result.stdout.trim())
+        bits.push(result.stdout.trim());
+    const joined = bits.join('\n');
+    return joined.length > limit ? joined.slice(-limit) : joined;
+}

package/dist/runner/pytestBddPlugin.js

@@ -7,6 +7,13 @@
 //
 // It only records — it never reconciles markers or aggregates capabilities. It
 // is connector-owned and never part of the LLM-generated step definitions.
+//
+// A step with no definition is recorded too (spec 52-3, AC 3.7): pytest-bdd
+// calls `pytest_bdd_step_func_lookup_error` for it and never `after_step`, so
+// without this hook the scenario went into the report as `passed` with no
+// steps — and a feature's checks, which have to prove they are red, could
+// have passed that proof on wiring nobody wrote. The server's parser refuses
+// an `undefined` step as a broken suite, which is the honest answer.
 export const PYTEST_BDD_PLUGIN = `# Written by the unitbob connector — do not edit.
 import json
 import os
@@ -62,6 +69,14 @@ def pytest_bdd_step_error(request, feature, scenario, step, step_func, step_func
     _record_step(scenario, step, "failed")
 
 
+def pytest_bdd_step_func_lookup_error(request, feature, scenario, step, exception):
+    entry = _UNITBOB_CURRENT.get(id(scenario))
+    if entry is not None:
+        entry["status"] = "failed"
+        entry["failure"] = "{}: {}".format(type(exception).__name__, exception)
+    _record_step(scenario, step, "undefined")
+
+
 def pytest_bdd_after_scenario(request, feature, scenario):
     entry = _UNITBOB_CURRENT.pop(id(scenario), None)
     if entry is not None:

package/dist/verbs/contractPrompt.js

@@ -5,21 +5,40 @@ import { Wire } from "../wire.js";
 // The server composes the whole prompt; the connector prints its plain-language
 // `message` and the copy-ready `prompt`. A 422 (not current / not failing /
 // unknown intent) surfaces via WireError; nothing is fabricated.
+//
+// `feature:<id>` stands in for the digest (spec 52-4, AC 1.3): a feature's
+// checks are not on the map to copy one from, so the id is resolved to
+// the digest of the feature's current checks through the same index `check`
+// runs from. The server words the brief itself, and answers 422 to `accept` —
+// a feature's scenarios change through the talk, not through an accept.
 export async function contractPrompt(config, args = [], deps) {
-    const suiteDigest = (args[0] ?? '').trim();
+    const selector = (args[0] ?? '').trim();
     const testId = (args[1] ?? '').trim();
     const intent = (args[2] ?? 'fix').trim();
-    if (!suiteDigest || !testId) {
-        throw new Error('Usage: unitbob contract-prompt <suite_digest> <test_id> [fix|accept]');
+    if (!selector || !testId) {
+        throw new Error('Usage: unitbob contract-prompt <suite_digest>|feature:<id> <test_id> [fix|accept]');
     }
     if (intent !== 'fix' && intent !== 'accept') {
         throw new Error(`intent must be "fix" or "accept" (got "${intent}").`);
     }
+    const wire = new Wire(config);
     const d = {
-        getContractPrompt: (digest, id, action) => new Wire(config).getContractPrompt(digest, id, action),
+        getContractPrompt: (digest, id, action) => wire.getContractPrompt(digest, id, action),
+        getSuiteIndex: () => wire.getSuiteIndex(),
         stdout: process.stdout,
         ...deps,
     };
+    const suiteDigest = selector.startsWith(FEATURE_SELECTOR) ? await featureDigest(d, selector.slice(FEATURE_SELECTOR.length)) : selector;
     const packet = await d.getContractPrompt(suiteDigest, testId, intent);
     d.stdout.write(`${packet.message}\n\n${packet.prompt}\n`);
 }
+const FEATURE_SELECTOR = 'feature:';
+// The digest of the feature's current checks. Only a feature being built has
+// them in the index: before the checks are written there is nothing to act on,
+// and after Finish they are part of the main suite, on the map like the rest.
+async function featureDigest(d, id) {
+    const item = (await d.getSuiteIndex()).feature_suites.find((entry) => String(entry.feature_id) === id);
+    if (!item)
+        throw new Error(`No feature ${id} has checks to act on — it is not being built, or it is finished.`);
+    return item.suite_digest;
+}

package/dist/verbs/featurePrepare.js

@@ -0,0 +1,49 @@
+import { requestPath, writeFeatureStartRequest } from "../files/featureStart.js";
+import { Wire } from "../wire.js";
+// Fetch the recipe and the behavioral assignment — the product capabilities of
+// the current map, with what each promises and where in the checkout it lives —
+// and write the host's task to `.unitbob/feature-start/request.json` (spec
+// 52-1). One request for the list, the same one `suite-prepare` makes; today's
+// check statuses are not asked for, because they belong on the feature's page
+// and not in the judgement of what the work may touch. No model is called,
+// no source is read, nothing is uploaded. A 409 (no current map) surfaces as a
+// WireError with the server's guidance and nothing is written.
+export async function featurePrepare(config, _args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        getRecipe: (name) => wire.getRecipe(name),
+        getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const [recipe, packets] = await Promise.all([d.getRecipe('feature_intent'), d.getSuitePacketsBatch()]);
+    const behavioral = packets.find((packet) => packet.suite_kind === 'behavioral');
+    if (!behavioral) {
+        throw new Error('The Unitbob server sent no behavioral assignment with the suite packets — it is older than this connector. ' +
+            'Update the server (or the connector) so the two agree, then retry.');
+    }
+    writeFeatureStartRequest(config.projectRoot, recipe, capabilitiesOf(behavioral));
+    d.stdout.write(`Feature request written to ${requestPath(config.projectRoot)}\n`);
+}
+// The six fields the recipe names, in the shape it names them. The contract
+// identity (`contract_key`, `case_marker`) rides in the assignment for the
+// suite recipe and is not copied: the host is naming what may be touched, not
+// writing tests.
+function capabilitiesOf(packet) {
+    const assignment = (packet.assignment ?? {});
+    const list = Array.isArray(assignment.capabilities) ? assignment.capabilities : [];
+    return list.map((entry) => {
+        const item = (typeof entry === 'object' && entry !== null ? entry : {});
+        return {
+            capability_id: String(item.capability_id ?? ''),
+            title: String(item.title ?? ''),
+            description: String(item.description ?? ''),
+            surfaces: strings(item.surfaces),
+            tables: strings(item.tables),
+            externals: strings(item.externals),
+        };
+    });
+}
+function strings(value) {
+    return Array.isArray(value) ? value.map((one) => String(one)) : [];
+}

package/dist/verbs/fixPrepare.js

@@ -1,20 +1,32 @@
 import { writeFixRequest } from "../files/fix.js";
 import { Wire } from "../wire.js";
-// Fetch the per-capability repair packet and write the host's task to
-// `.unitbob/fix/request.json`. No recipe fetch, no upload — the host reads its own
-// source and the local spec file, then either fixes code (next `/unitbob check`
-// shows the result) or accepts the change and republishes the suite (spec 26). A
-// 422 from the server (non-failed / stale / no suite) surfaces via WireError;
-// nothing is written.
+// Two forms, one verb.
+//
+// Without an id (spec 54-1): print the list a fix starts from — every red guard
+// of both maps under the digest it is red on, with the line that says whether
+// it ever passed on that suite. The server words it; the connector prints it
+// as it is. Nothing is written: the list is read, the brief comes next from
+// `contract-prompt` with the digest copied off this list.
+//
+// With an id (spec 26): fetch the per-capability repair packet and write the
+// host's task to `.unitbob/fix/request.json`. No recipe fetch, no upload — the
+// host reads its own source and the local spec file, then either fixes code
+// (next `/unitbob check` shows the result) or accepts the change and
+// republishes the suite. A 422 from the server (non-failed / stale / no suite)
+// surfaces via WireError; nothing is written.
 export async function fixPrepare(config, args = [], deps) {
-    const interfaceId = (args[0] ?? '').trim();
-    if (!interfaceId)
-        throw new Error('Usage: unitbob fix-prepare <interface_id>');
     const d = {
+        getRedList: () => new Wire(config).getRedList(),
         getFixPacket: (id) => new Wire(config).getFixPacket(id),
         stdout: process.stdout,
         ...deps,
     };
+    const interfaceId = (args[0] ?? '').trim();
+    if (!interfaceId) {
+        const list = await d.getRedList();
+        d.stdout.write(`${list.message}\n`);
+        return;
+    }
     const packet = await d.getFixPacket(interfaceId);
     writeFixRequest(config.projectRoot, interfaceId, packet);
     d.stdout.write(`${packet.message}\n`);

package/dist/verbs/knowledgePrepare.js

@@ -0,0 +1,39 @@
+import { knowledgeRequestPath, parseFeatureId, writeKnowledgeRequest } from "../files/features.js";
+import { Wire } from "../wire.js";
+// The statuses a feature can be talked through in: not yet talked through,
+// talked through and open to a second talk (spec 52-2, AC 2.1), or its checks
+// written — a talk then withdraws them, out loud (spec 52-3, AC 2.9).
+const TALKABLE = new Set(['intent', 'knowledge', 'red']);
+// Two forms (spec 52-2, AC 2.1). Without an id, the list: one line per feature
+// the talk can start on, so the host finds the one the person means by its
+// words — and the server's own sentence when there is none; the connector
+// words no state of its own. With an id, the host's task: the recipe and the
+// packet the server built, written to `.unitbob/features/<id>/request.json`
+// next to where `knowledge.md` will go. No model is called, nothing is
+// uploaded.
+export async function knowledgePrepare(config, args = [], deps) {
+    const wire = new Wire(config);
+    const d = {
+        listFeatures: () => wire.listFeatures(),
+        getRecipe: (name) => wire.getRecipe(name),
+        getKnowledgePacket: (id) => wire.getKnowledgePacket(id),
+        stdout: process.stdout,
+        ...deps,
+    };
+    if (args.length === 0) {
+        const list = await d.listFeatures();
+        const talkable = list.features.filter((feature) => TALKABLE.has(feature.status));
+        if (talkable.length === 0) {
+            d.stdout.write(`${list.empty_text}\n`);
+            return;
+        }
+        for (const feature of talkable) {
+            d.stdout.write(`${feature.feature_id}  ${feature.title} (${feature.status})\n`);
+        }
+        return;
+    }
+    const featureId = parseFeatureId(args[0], 'knowledge-prepare');
+    const [recipe, packet] = await Promise.all([d.getRecipe('feature_grill'), d.getKnowledgePacket(featureId)]);
+    writeKnowledgeRequest(config.projectRoot, featureId, recipe, packet);
+    d.stdout.write(`Knowledge request written to ${knowledgeRequestPath(config.projectRoot, featureId)}\n`);
+}

package/dist/verbs/mapPrepare.js

@@ -1,7 +1,7 @@
 import { ensureUnitbobIgnored, ignoreExclusions, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
 import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
 import { describeRouteInventory, extractRouteInventory, } from "../surfaces/routeInventory.js";
-import { Wire } from "../wire.js";
+import { Wire, WireError } from "../wire.js";
 export async function mapPrepare(config, _args = [], deps) {
     const wire = new Wire(config);
     const actual = {
@@ -10,7 +10,9 @@ export async function mapPrepare(config, _args = [], deps) {
         runGraphifyExtractKeyless,
         extractRouteInventory,
         getRecipe: (name) => wire.getRecipe(name),
+        listFeatures: () => wire.listFeatures(),
         stdout: process.stdout,
+        stderr: process.stderr,
         ...deps,
     };
     actual.ensureUnitbobIgnored(config.projectRoot);
@@ -44,18 +46,19 @@ export async function mapPrepare(config, _args = [], deps) {
     // us there reads as a hang.
     actual.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
     const inventory = await actual.extractRouteInventory(config.projectRoot);
-    const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
+    const [decompose, relate, extractSurfaces, decomposeSurfaces, existing] = await Promise.all([
         actual.getRecipe('decompose'),
         actual.getRecipe('relate'),
         actual.getRecipe('extract_surfaces'),
         actual.getRecipe('decompose_surfaces'),
+        existingCapabilities(actual),
     ]);
     const packet = writeMapBuildRequest(config.projectRoot, {
         decompose,
         relate,
         extract_surfaces: extractSurfaces,
         decompose_surfaces: decomposeSurfaces,
-    }, inventory.status === 'written' ? inventory.path : undefined);
+    }, inventory.status === 'written' ? inventory.path : undefined, existing);
     actual.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
     actual.stdout.write(`${describeRouteInventory(inventory)}\n`);
     actual.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
@@ -63,3 +66,26 @@ export async function mapPrepare(config, _args = [], deps) {
         `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +
         'recipes.decompose_surfaces) — then run `unitbob put-map-build`.\n');
 }
+// The capabilities finished features added to the map (spec 52-4, AC 5.1):
+// by id, title and the intent as said — no addresses, the recipe matches by
+// meaning. Only finished features: an open one is not on the map yet. A
+// server older than the fields sends rows without a capability id, and one
+// older than the route answers 404; both read as none, quietly, and the
+// recipe skips its paragraph (AC 7.3). Any other failure of the list is not
+// a reason to stop a map build either — but it is said, on stderr, because a
+// map built without the finished features' ids is one that may redraw them.
+async function existingCapabilities(d) {
+    let features;
+    try {
+        features = (await d.listFeatures()).features;
+    }
+    catch (err) {
+        if (!(err instanceof WireError && err.status === 404)) {
+            d.stderr.write(`Could not list finished features — the map is built without them: ${err.message}\n`);
+        }
+        return [];
+    }
+    return features
+        .filter((feature) => feature.status === 'done' && typeof feature.capability_id === 'string')
+        .map((feature) => ({ id: feature.capability_id, title: feature.title, description: feature.intent ?? '' }));
+}

package/dist/verbs/putFeature.js

@@ -0,0 +1,21 @@
+import { readFeatureAnswer } from "../files/featureStart.js";
+import { enterUrl } from "../links.js";
+import { Wire } from "../wire.js";
+// Read the host's answer and record the feature (spec 52-1). The server checks
+// every id against the current map and words the sentence; this prints it and
+// the link to the feature's page through the exchanger, like every link a
+// person gets from the terminal (spec 33). A 422 — an id not on the map — is
+// let through as a WireError with both id lists in its text, so the host
+// corrects its file and runs this again. Nothing is created locally: the
+// feature's folder, its knowledge file and its tests belong to later specs.
+export async function putFeature(config, _args = [], deps) {
+    const d = {
+        postFeature: (payload) => new Wire(config).postFeature(payload),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const answer = readFeatureAnswer(config.projectRoot);
+    const recorded = await d.postFeature(answer);
+    d.stdout.write(`${recorded.message}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+}

package/dist/verbs/putKnowledge.js

@@ -0,0 +1,21 @@
+import { parseFeatureId, readKnowledge } from "../files/features.js";
+import { enterUrl } from "../links.js";
+import { Wire } from "../wire.js";
+// Send `knowledge.md` as text (spec 52-2, AC 2.2) and print the server's
+// sentence and the link to the feature's page through the exchanger, like
+// every link a person gets from the terminal (spec 33). The shape is checked
+// on the server only (Non-Goals); a 422 comes back through the wire as a
+// WireError whose text already holds one line per problem, both sides, and
+// this lets it through so the host fixes the file and runs this again.
+export async function putKnowledge(config, args = [], deps) {
+    const d = {
+        putKnowledge: (id, knowledge) => new Wire(config).putKnowledge(id, knowledge),
+        stdout: process.stdout,
+        ...deps,
+    };
+    const featureId = parseFeatureId(args[0], 'put-knowledge');
+    const text = readKnowledge(config.projectRoot, featureId);
+    const recorded = await d.putKnowledge(featureId, text);
+    d.stdout.write(`${recorded.message}\n`);
+    d.stdout.write(`${enterUrl(config, recorded.url)}\n`);
+}