razzou-harness 0.1.2 → 0.2.0

package/dist/ci/harness-ci.js

@@ -181,6 +181,42 @@ export function prKind(author, branch, bot) {
         return 'Harness';
     return 'Owner';
 }
+/**
+ * A plan's kind, from its features' (v3 §3.1): CODE with no `infra` feature, INFRA with
+ * only `infra` features, MIXED otherwise. A feature without a kind is an `app` one. The
+ * same rule as the daemon's `planKind`, kept here so this file stands alone.
+ */
+export function planKindOf(features) {
+    const infra = features.filter((f) => f.kind === 'infra').length;
+    return infra === 0 ? 'CODE' : infra === features.length ? 'INFRA' : 'MIXED';
+}
+/**
+ * The plan-kind rules of a Plan PR (v3 §3.1), from the plan file on the base branch: a
+ * tag in the title must be the plan's kind, and a CODE plan stays off the Terraform
+ * folder, so infrastructure can't reach main as code. The tag grants nothing, and a
+ * title without one, from an older daemon, passes.
+ */
+async function planKindProblems(input, config) {
+    const [, module, plan] = /^plan\/([^/]+)\/([^/]+)$/.exec(input.branch) ?? [];
+    if (!module || !plan)
+        return [];
+    const file = `harness/modules/${module}/plans/${plan}.json`;
+    const definition = parseJson(await input.base.read(file));
+    if (!definition || !Array.isArray(definition.features))
+        return [`${file} is missing or unreadable on the base branch, so the plan's kind is unknown`];
+    const kind = planKindOf(definition.features);
+    const problems = [];
+    const tag = /(?:^|\s)-(CODE|INFRA|MIXED)-(?:\s|$)/.exec(input.title)?.[1];
+    if (tag && tag !== kind)
+        problems.push(`the title says -${tag}-, but ${module}/${plan} is a ${kind} plan on the base branch: its features' kinds decide`);
+    if (kind === 'CODE' && config?.terraform && typeof config.terraform === 'object') {
+        const dir = (config.terraform.dir || 'iac').replace(/\/+$/, '');
+        const touched = input.changedPaths.filter((p) => p === dir || p.startsWith(`${dir}/`));
+        if (touched.length > 0)
+            problems.push(`a CODE plan may not change ${dir}/: infrastructure gets plans of its own (v3 §3.1); changed: ${touched.join(', ')}`);
+    }
+    return problems;
+}
 /** The `verify` job: the problems that make a PR fail, or none. */
 export async function verify(input) {
     const config = parseJson(await input.base.read('harness/config.json'));
@@ -195,6 +231,8 @@ export async function verify(input) {
         for (const problem of await lockfileProblems(input.head))
             problems.push(`package-lock.json: ${problem}`);
     }
+    if (kind === 'Plan')
+        problems.push(...(await planKindProblems(input, config)));
     if (kind === 'Arch') {
         const rules = await protectionRules(input.head);
         for (const path of input.changedPaths.filter((p) => !archMayChange(p, rules))) {

package/dist/cli.js

@@ -1,26 +1,37 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
 import { computeLock, directoryReader } from './ci/harness-ci.js';
 import { isAlive, packageRoot, readDaemonInfo, runDaemon, version } from './daemon/main.js';
 import { ConfigSchema, requiredChecks } from './design/schemas.js';
+import { loadAppCredentials } from './github/app.js';
 import { applyRepositoryRules, checkApp, createApp, installCi } from './github/setup.js';
 import { doctor } from './setup/doctor.js';
 import { CHECKLIST, init } from './setup/init.js';
 import { recover } from './setup/recover.js';
+import { setup } from './setup/setup.js';
 import { sleep } from './util.js';
 const HELP = `harness ${version}
 
 Usage: harness <command> [--dir <project>]
 
+  setup [--repo <owner/name>] [--owner <login>]
+                     Set up this machine and the project: every step the harness can do, asking only for
+                     what is yours (a login, a token, a click on GitHub); run it again any time
   init [--repo <owner/name>] [--owner <login>]
                      Write the harness's files into this repository, and print the setup checklist
   up                 Run the daemon for the project (foreground) and open the dashboard
   down               Stop the running daemon; sandboxes keep their state
   status             Show plans, features and the pipeline
   resume             Lift a pause of the pipeline
+  mode [manual|swarm]
+                     Show the mode, or switch it and apply the mode's rules on main with your gh:
+                     in Swarm the daemon merges plans (docs/architecture/proposal-v3.md)
+  budget --owner-hours <n> | --agent-hours <n>
+                     Set the hours of your time for the whole project, or the agent-hours threshold
   retry <m/p/f>      Grant one more attempt to an escalated feature (--note: guidance)
   module new <id> <title>
                      Start a module: its Architect's sandbox and conversation
@@ -38,8 +49,8 @@ Usage: harness <command> [--dir <project>]
                      Check that the App is installed on the repository and can get a token
   install-ci [--owner <login>]
                      Write the harness workflow, its CI script and CODEOWNERS into the project
-  github-setup --repo <owner/repo>
-                     Apply merge settings and the main ruleset, with your own gh login
+  github-setup --repo <owner/repo> [--mode manual|swarm]
+                     Apply merge settings and the main ruleset of the mode (the daemon's, by default), with your own gh login
   lock               Write harness/lock.json, the hashes of every protected file and field
   doctor [--probe] [--build-images]
                      Check this machine and the project, and set up the providers;
@@ -58,6 +69,9 @@ async function main() {
             name: { type: 'string' },
             repo: { type: 'string' },
             owner: { type: 'string' },
+            mode: { type: 'string' },
+            'owner-hours': { type: 'string' },
+            'agent-hours': { type: 'string' },
             probe: { type: 'boolean' },
             'build-images': { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
@@ -75,24 +89,65 @@ async function main() {
         case 'status':
             return status(harnessDir);
         case 'resume':
-            return ownerAction(harnessDir, '/api/resume', {});
+            return void await ownerAction(harnessDir, '/api/resume', {});
+        case 'mode': {
+            if (!argument) {
+                const file = join(harnessDir, 'state.json');
+                const state = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined;
+                console.log(state?.mode ?? 'manual');
+                return;
+            }
+            if (argument !== 'manual' && argument !== 'swarm')
+                throw new Error('usage: harness mode [manual|swarm]');
+            const result = await ownerAction(harnessDir, '/api/mode', { mode: argument });
+            // GitHub's rules on main differ per mode, and only the owner's gh may change them (v3 §2.1): done here, in the same command.
+            const repo = projectConfig(projectDir)?.project.repo;
+            if (result.error || !repo)
+                return;
+            try {
+                await applyRules(projectDir, harnessDir, repo, argument);
+            }
+            catch (error) {
+                console.log(`GitHub's rules on main were not changed: ${error.message}\nRun \`harness github-setup --repo ${repo}\` with gh logged in as an admin of the repository.`);
+            }
+            return;
+        }
+        case 'budget': {
+            const hours = (key) => (values[key] === undefined ? undefined : Number(values[key]));
+            const budgets = { ownerHours: hours('owner-hours'), agentHours: hours('agent-hours') };
+            if ((budgets.ownerHours === undefined && budgets.agentHours === undefined) || [budgets.ownerHours, budgets.agentHours].some((h) => h !== undefined && (!Number.isFinite(h) || h <= 0))) {
+                throw new Error('usage: harness budget --owner-hours <n> | --agent-hours <n>, with positive numbers');
+            }
+            const info = readDaemonInfo(harnessDir);
+            if (info && isAlive(info.pid))
+                return void (await ownerAction(harnessDir, '/api/budgets', budgets));
+            // The daemon is down: the hours wait for it in .harness/setup.json (v4 §5).
+            if (budgets.agentHours !== undefined)
+                throw new Error('the agent-hours threshold needs the daemon running: `harness up`');
+            const file = join(harnessDir, 'setup.json');
+            const pending = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+            mkdirSync(harnessDir, { recursive: true });
+            writeFileSync(file, `${JSON.stringify({ ...pending, ownerHours: budgets.ownerHours }, null, 2)}\n`);
+            console.log(`${budgets.ownerHours} hours of your time: the daemon records it when it starts (harness up).`);
+            return;
+        }
         case 'retry':
             if (!argument)
                 throw new Error('usage: harness retry <module/plan/feature>');
-            return ownerAction(harnessDir, '/api/retry', { feature: argument, note: values.note });
+            return void await ownerAction(harnessDir, '/api/retry', { feature: argument, note: values.note });
         case 'message':
             if (!argument)
                 throw new Error('usage: harness message <text>');
-            return ownerAction(harnessDir, '/api/message', { text: positionals.slice(1).join(' ') });
+            return void await ownerAction(harnessDir, '/api/message', { text: positionals.slice(1).join(' ') });
         case 'answer':
             if (!argument || positionals.length < 3)
                 throw new Error('usage: harness answer <request-id> <text>');
-            return ownerAction(harnessDir, '/api/answer', { id: argument, text: positionals.slice(2).join(' ') });
+            return void await ownerAction(harnessDir, '/api/answer', { id: argument, text: positionals.slice(2).join(' ') });
         case 'module': {
             const [, id, ...title] = positionals.slice(1);
             if (argument !== 'new' || !id)
                 throw new Error('usage: harness module new <id> <title>');
-            return ownerAction(harnessDir, '/api/modules', { id, title: title.join(' ') });
+            return void await ownerAction(harnessDir, '/api/modules', { id, title: title.join(' ') });
         }
         case 'attach':
             return attach(harnessDir, argument);
@@ -100,7 +155,7 @@ async function main() {
             const version = Number((positionals[2] ?? '').replace(/^v/, ''));
             if (!argument || !Number.isInteger(version) || version < 1)
                 throw new Error('usage: harness accept <module> <vN>');
-            return ownerAction(harnessDir, '/api/accept', { module: argument, version });
+            return void await ownerAction(harnessDir, '/api/accept', { module: argument, version });
         }
         case 'actions':
             return listActions(harnessDir);
@@ -108,7 +163,7 @@ async function main() {
             const [module, action] = (argument ?? '').split('/');
             if (!module || !action)
                 throw new Error('usage: harness done <module>/<action> [--note <text>]');
-            return ownerAction(harnessDir, '/api/actions/done', { module, action, note: values.note });
+            return void await ownerAction(harnessDir, '/api/actions/done', { module, action, note: values.note });
         }
         case 'github-app':
             return githubApp(argument, values);
@@ -120,12 +175,29 @@ async function main() {
         }
         case 'github-setup': {
             if (!values.repo)
-                throw new Error('usage: harness github-setup --repo <owner/repo>');
-            const configFile = join(projectDir, 'harness', 'config.json');
-            const required = existsSync(configFile) ? requiredChecks(ConfigSchema.parse(JSON.parse(readFileSync(configFile, 'utf8')))) : ['verify', 'checks'];
-            for (const line of await applyRepositoryRules(values.repo, required))
-                console.log(`set: ${line}`);
-            return;
+                throw new Error('usage: harness github-setup --repo <owner/repo> [--mode manual|swarm]');
+            if (values.mode !== undefined && values.mode !== 'manual' && values.mode !== 'swarm')
+                throw new Error('--mode is manual or swarm');
+            return applyRules(projectDir, harnessDir, values.repo, values.mode);
+        }
+        case 'setup': {
+            if (process.stdin.isTTY !== true)
+                throw new Error('harness setup needs a terminal: it asks for what only you can give. `harness doctor` lists what is missing.');
+            return setup({
+                projectDir,
+                packageDir: packageRoot,
+                version,
+                ...(values.repo ? { repo: values.repo } : {}),
+                ...(values.owner ? { owner: values.owner } : {}),
+                say: (line) => console.log(line),
+                ask: (question) => ask(question),
+                open: (url) => spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).on('error', () => { }).unref(),
+                interactive: (file, args) => spawnSync(file, args, { stdio: 'inherit' }).status ?? 1,
+                up: async () => {
+                    await runDaemon(projectDir);
+                    process.exit(0);
+                },
+            });
         }
         case 'doctor':
             return runDoctor(projectDir, values);
@@ -158,6 +230,42 @@ async function main() {
             console.log(HELP);
     }
 }
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The project's configuration, when the directory has one. */
+function projectConfig(projectDir) {
+    const configFile = join(projectDir, 'harness', 'config.json');
+    return existsSync(configFile) ? ConfigSchema.parse(JSON.parse(readFileSync(configFile, 'utf8'))) : undefined;
+}
+/** Merge settings and the ruleset of the mode on main, with the owner's own gh: the daemon's mode, unless `mode` says otherwise (v3 §2.1). */
+async function applyRules(projectDir, harnessDir, repo, mode) {
+    const config = projectConfig(projectDir);
+    const required = config ? requiredChecks(config) : ['verify', 'checks'];
+    const stateFile = join(harnessDir, 'state.json');
+    const snapshot = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, 'utf8')) : undefined;
+    const effective = mode ?? snapshot?.mode ?? 'manual';
+    let options = { mode: effective };
+    if (effective === 'swarm') {
+        const statuses = (config?.swarm ?? ConfigSchema.shape.swarm.parse(undefined)).requiredStatuses;
+        let appId;
+        try {
+            appId = loadAppCredentials().appId;
+        }
+        catch {
+            appId = undefined;
+        }
+        options = { mode: effective, statuses, ...(appId !== undefined ? { appId } : {}) };
+    }
+    for (const line of await applyRepositoryRules(repo, required, options))
+        console.log(`set: ${line}`);
+}
 async function githubApp(action, values) {
     if (action === 'create') {
         if (!values.org)
@@ -249,6 +357,7 @@ async function ownerAction(harnessDir, path, body) {
     });
     const result = (await response.json());
     console.log(result.done ? 'done' : result.error ?? 'nothing to do');
+    return result;
 }
 /** The Architect's terminal, attached in this one. Detaching leaves the Architect running. */
 function attach(harnessDir, module) {

package/dist/daemon/architects.js

@@ -116,7 +116,7 @@ export class Architects {
             return folder;
         };
         copyFileSync(join(o.options.packageDir, 'roles', 'architect.md'), join(staging('harness'), 'architect.md'));
-        writeFileSync(join(staging('harness'), 'welcome.md'), welcome(module));
+        writeFileSync(join(staging('harness'), 'welcome.md'), welcome(module, o.state.budgets.ownerHours !== undefined));
         for (const file of ['architect.md', 'welcome.md'])
             await o.driver.upload(sandbox, join(staging('harness'), file), p.harness);
         await o.uploadAgentFiles(sandbox, 'architect', dir);
@@ -264,13 +264,16 @@ export class Architects {
     }
 }
 /** The first prompt of a session: a new module, or one whose sandbox was recreated without its conversation. */
-function welcome(module) {
+function welcome(module, budgeted) {
     const latest = module.proposals.at(-1);
+    // The owner's time is budgeted: the Architect designs owner actions within it (v3 §4.1).
+    const budget = budgeted ? ['The owner budgets their time: call get_owner_time before you propose, and estimate every owner action.'] : [];
     if (!latest) {
         return clip([
             `[harness] You are the Architect of the new module "${module.module}": ${module.title}.`,
             'Read README.md, ARCHITECTURE.md and the other modules\' designs in harness/modules/ first.',
             'Then greet the owner in two lines and wait: they will tell you what this module is for. Then use the grill-me skill.',
+            ...budget,
         ].join('\n'), 2000);
     }
     const where = {
@@ -285,5 +288,6 @@ function welcome(module) {
         'Your sandbox was recreated, and your earlier conversation is gone.',
         `Your proposals are in harness/modules/${module.module}/proposals/. ${where}`,
         'Read them, README.md and ARCHITECTURE.md, then greet the owner in two lines and wait.',
+        ...budget,
     ].join('\n'), 2000);
 }

package/dist/daemon/design.js

@@ -1,4 +1,5 @@
 import { archMayChange, computeLock, protectionRules } from '../ci/harness-ci.js';
+import { moduleOwnerTime, ownerTimeProblems } from '../design/owner-time.js';
 import { checkScripts, definitionHash, loadDesign } from '../design/schemas.js';
 import { HARNESS } from '../git/repo.js';
 import { clip } from '../util.js';
@@ -54,6 +55,9 @@ export async function submitDesign(o, module, summary, head) {
             }
         }
     }
+    // Once the owner budgets their time, every owner action is estimated, and the module fits what is available (v3 §4.1).
+    if (mine)
+        problems.push(...ownerTimeProblems(await o.ownerTime(), moduleOwnerTime(mine, o.state)));
     if (problems.length > 0 || !mine)
         return { ok: false, problems };
     // The new checks, run once on the repository as it is: nothing is built yet, so they should fail.

package/dist/daemon/items.js

@@ -2,10 +2,12 @@ import { definitionHash } from '../design/schemas.js';
 import { countedAttempts, featureKey, planKey } from '../state/state.js';
 import { clip, tail } from '../util.js';
 import { attemptRefName, refOf } from './refs.js';
-export function pendingItems(o, module) {
+/** What waits for a Manager: the items of its module, or of its plan alone for a plan's Manager (v3 §6.4). */
+export function pendingItems(o, scope) {
+    const { module, plan: only } = scope;
     const questions = [];
     const others = [];
-    for (const feature of Object.values(o.state.features).filter((f) => f.module === module)) {
+    for (const feature of Object.values(o.state.features).filter((f) => f.module === module && (only === undefined || f.plan === only))) {
         const last = feature.attempts.at(-1);
         if (!last)
             continue;
@@ -22,7 +24,7 @@ export function pendingItems(o, module) {
     }
     const rounds = o.design.config.brakes.ciFixRounds;
     const deployRounds = o.design.config.brakes.deployFixRounds;
-    for (const plan of Object.values(o.state.plans).filter((p) => p.module === module)) {
+    for (const plan of Object.values(o.state.plans).filter((p) => p.module === module && (only === undefined || p.plan === only))) {
         if ((plan.status === 'deploy_failed' || plan.status === 'verify_failed') && (plan.deployFixRounds ?? 0) < deployRounds) {
             const key = planKey(plan);
             const what = plan.status === 'deploy_failed' ? 'DEPLOY FAILED' : 'POST-DEPLOY CHECKS FAILED';
@@ -202,7 +204,25 @@ export function mailText(o, manager, mail) {
         return [`[harness] ANSWER from the owner (request ${mail.requestId})`, '', `You asked: ${clip(question, 800)}`, '', `Answer: ${mail.text}`].join('\n');
     }
     const module = o.design.modules.find((m) => m.id === manager.module);
-    const plans = (module?.plans ?? []).map((p) => `- ${p.id} "${p.title}": ${p.features.map((f) => `${f.id} "${f.title}"`).join(', ')}`);
+    const features = (p) => p.features.map((f) => `${f.id} "${f.title}"`).join(', ');
+    if (manager.plan) {
+        // A plan's Manager, in Swarm (v3 §6.4): its plan, and where the module's other plans stand.
+        const mine = module?.plans.find((p) => p.id === manager.plan);
+        const others = (module?.plans ?? []).filter((p) => p.id !== manager.plan).map((p) => {
+            const status = o.state.plans[`${manager.module}/${p.id}`]?.status;
+            const where = status === 'completed' ? 'complete' : status ? `${status.replace(/_/g, ' ')}, with its own Manager` : 'not started';
+            return `- ${p.id} "${p.title}": ${where}`;
+        });
+        return [
+            `[harness] WELCOME: you are the Manager of plan ${manager.plan} "${mine?.title ?? ''}" of module "${manager.module}".`,
+            '',
+            `Its features: ${mine ? features(mine) : '(none)'}.`,
+            ...(others.length > 0 ? ['', "The module's other plans, which are not yours:", ...others] : []),
+            '',
+            `The plan is harness/modules/${manager.module}/plans/${manager.plan}.json in your clone, next to the others. Read it now, with ARCHITECTURE.md and README.md if they exist, so you're ready for questions and reviews. Then reply in one line and wait for the next item.`,
+        ].join('\n');
+    }
+    const plans = (module?.plans ?? []).map((p) => `- ${p.id} "${p.title}": ${features(p)}`);
     return [
         `[harness] WELCOME: you are the Manager of module "${manager.module}".`,
         '',