opencode-agent-harness 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +590 -2
- package/bin/agent-harness.js +3059 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +48 -4
- package/templates/.agents/AGENTS.md +204 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1864 -0
- package/templates/scripts/board-service.sh +207 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +277 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +260 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +469 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +427 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +284 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +183 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +212 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +261 -0
|
@@ -0,0 +1,514 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
/*
|
|
4
|
+
* orient — one-call session orientation.
|
|
5
|
+
*
|
|
6
|
+
* A resume/claim session otherwise re-derives the same handful of facts by
|
|
7
|
+
* hand: `git rev-parse --show-toplevel` + `git branch --show-current`
|
|
8
|
+
* (114 calls / 103 sessions in the 2026-09 LibraryOS recon), a `git status`,
|
|
9
|
+
* `serve.js list`, `npm run test:capacity`, the checkpoint, the board row, the
|
|
10
|
+
* owned files, and the last device-run summary — a single F-291 resume spent 21
|
|
11
|
+
* such calls before any real work. This gathers them deterministically in ONE
|
|
12
|
+
* invocation.
|
|
13
|
+
*
|
|
14
|
+
* Pure gatherer + thin CLI. Every source is optional and degrades to a labelled
|
|
15
|
+
* `unavailable` line — orient never invents a value and never throws on a
|
|
16
|
+
* missing file (a fresh checkout has no checkpoint, no lease, no `.serve/`).
|
|
17
|
+
*
|
|
18
|
+
* Usage:
|
|
19
|
+
* node scripts/orient.js [--feature <id>] [--json] [--root <dir>]
|
|
20
|
+
*
|
|
21
|
+
* The same gatherer is exported for the `.opencode/plugins/orient.ts` wrapper and
|
|
22
|
+
* for unit tests (inject `git`/`fs`/`readCheckpoint` to keep it hermetic).
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
const fs = require("fs");
|
|
26
|
+
const path = require("path");
|
|
27
|
+
const { spawnSync } = require("child_process");
|
|
28
|
+
const checkpoint = require("./checkpoint.js");
|
|
29
|
+
const capacity = require("./qa/capacity-lib.js");
|
|
30
|
+
|
|
31
|
+
const SCHEMA = "orient/1";
|
|
32
|
+
|
|
33
|
+
function safe(fn, fallback = null) {
|
|
34
|
+
try {
|
|
35
|
+
const v = fn();
|
|
36
|
+
return v == null ? fallback : v;
|
|
37
|
+
} catch (_) {
|
|
38
|
+
return fallback;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/* `git -C <root> <args>` trimmed stdout, or null. Injected for tests. */
|
|
43
|
+
function gitRunner(root) {
|
|
44
|
+
return (args) => {
|
|
45
|
+
const r = spawnSync("git", ["-C", root, ...args], {
|
|
46
|
+
encoding: "utf8",
|
|
47
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
48
|
+
timeout: 5000,
|
|
49
|
+
});
|
|
50
|
+
if (r.status !== 0 || typeof r.stdout !== "string") return null;
|
|
51
|
+
return r.stdout.trim();
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/* "main" when the repo's `.git` is a directory; "linked" when it is a file
|
|
56
|
+
* (a `git worktree`). Walk up from `p` without invoking git. */
|
|
57
|
+
function checkoutKind(p) {
|
|
58
|
+
let dir = path.resolve(p);
|
|
59
|
+
while (dir !== path.dirname(dir) && !fs.existsSync(dir)) dir = path.dirname(dir);
|
|
60
|
+
try {
|
|
61
|
+
if (!fs.statSync(dir).isDirectory()) dir = path.dirname(dir);
|
|
62
|
+
} catch (_) {
|
|
63
|
+
/* fall through to the walk */
|
|
64
|
+
}
|
|
65
|
+
for (let i = 0; i < 64; i++) {
|
|
66
|
+
try {
|
|
67
|
+
return fs.statSync(path.join(dir, ".git")).isDirectory() ? "main" : "linked";
|
|
68
|
+
} catch (_) {
|
|
69
|
+
/* no .git here */
|
|
70
|
+
}
|
|
71
|
+
const parent = path.dirname(dir);
|
|
72
|
+
if (parent === dir) return null;
|
|
73
|
+
dir = parent;
|
|
74
|
+
}
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function harnessVersion(root) {
|
|
79
|
+
return safe(() => JSON.parse(fs.readFileSync(path.join(root, ".harness.json"), "utf8")).version, null);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function lastE2eRun(root) {
|
|
83
|
+
return safe(
|
|
84
|
+
() => {
|
|
85
|
+
const p = path.join(root, ".serve", "mobile-e2e-last-run.json");
|
|
86
|
+
const doc = JSON.parse(fs.readFileSync(p, "utf8"));
|
|
87
|
+
const total = doc.total || doc.flows || doc.flowCount;
|
|
88
|
+
const failed = doc.failed != null ? doc.failed : Array.isArray(doc.failures) ? doc.failures.length : null;
|
|
89
|
+
return { at: doc.startedAt || doc.at || null, total: total != null ? total : null, failed, path: p };
|
|
90
|
+
},
|
|
91
|
+
null
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/* The last nightly E2E cycle verdict, from `.agents/qa-runs/nightly/latest.json`
|
|
96
|
+
* (written by scripts/nightly.js). This is the morning signal: a red nightly has
|
|
97
|
+
* already reconciled the board (validated fixes / reopened rows / new rows). */
|
|
98
|
+
function latestNightly(root) {
|
|
99
|
+
return safe(
|
|
100
|
+
() => {
|
|
101
|
+
const p = path.join(root, ".agents", "qa-runs", "nightly", "latest.json");
|
|
102
|
+
const doc = JSON.parse(fs.readFileSync(p, "utf8"));
|
|
103
|
+
const failures = Array.isArray(doc.failures) ? doc.failures : [];
|
|
104
|
+
const reconcile = Array.isArray(doc.reconcile) ? doc.reconcile : [];
|
|
105
|
+
return {
|
|
106
|
+
verdict: doc.verdict || null,
|
|
107
|
+
at: doc.finishedAt || doc.startedAt || doc.stamp || null,
|
|
108
|
+
failed: failures.length,
|
|
109
|
+
reopened: reconcile.filter((a) => a.kind === "reopen").length,
|
|
110
|
+
added: reconcile.filter((a) => a.kind === "add").length,
|
|
111
|
+
path: p,
|
|
112
|
+
};
|
|
113
|
+
},
|
|
114
|
+
null
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/* Read the board JSON via the canonical CLI so orient never re-implements the
|
|
119
|
+
* board parser. Returns { inprogress, queued, open, active } or null. */
|
|
120
|
+
function boardSnapshot(root, run) {
|
|
121
|
+
const r = run(["scripts/backlog.js", "list", "--all", "--json"]);
|
|
122
|
+
if (!r) return null;
|
|
123
|
+
return safe(() => JSON.parse(r), null);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function ownedFor(root, feature) {
|
|
127
|
+
if (!feature) return null;
|
|
128
|
+
const p = path.join(root, ".agents", "memory", "owned-files.md");
|
|
129
|
+
const src = safe(() => fs.readFileSync(p, "utf8"), null);
|
|
130
|
+
if (!src) return null;
|
|
131
|
+
const re = new RegExp(`^\\s*[-*]\\s+${feature.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:\\s*(.+)$`, "im");
|
|
132
|
+
const m = src.match(re);
|
|
133
|
+
return m ? m[1].trim() : null;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/* The memory files the operating rules name as session-start reads. Their
|
|
137
|
+
* content is project-owned and open-ended, so orient does not attempt to
|
|
138
|
+
* summarize prose — it extracts the stable, machine-shaped facts (the `##`
|
|
139
|
+
* section index and the FIRST markdown table) and caps them, so a session can
|
|
140
|
+
* often answer its orientation question without opening the file at all. */
|
|
141
|
+
const MEMORY_FILES = [
|
|
142
|
+
"environments.md",
|
|
143
|
+
"model-routing.md",
|
|
144
|
+
"orchestration.md",
|
|
145
|
+
"locations.md",
|
|
146
|
+
"product-principles.md",
|
|
147
|
+
"dev-loop.md",
|
|
148
|
+
];
|
|
149
|
+
const MAX_SECTIONS = 8;
|
|
150
|
+
const MAX_TABLE_ROWS = 6;
|
|
151
|
+
const MAX_CELL = 64;
|
|
152
|
+
|
|
153
|
+
function splitRow(line) {
|
|
154
|
+
return String(line)
|
|
155
|
+
.replace(/^\s*\|/, "")
|
|
156
|
+
.replace(/\|\s*$/, "")
|
|
157
|
+
.split("|")
|
|
158
|
+
.map((c) => c.trim())
|
|
159
|
+
.map((c) => (c.length > MAX_CELL ? c.slice(0, MAX_CELL - 1) + "\u2026" : c));
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function isTableSeparator(line) {
|
|
163
|
+
return /^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(line) && line.includes("-");
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/* First markdown table in the source: { header, rows } or null. Pure. */
|
|
167
|
+
function parseFirstTable(src) {
|
|
168
|
+
const lines = String(src).split(/\r?\n/);
|
|
169
|
+
for (let i = 0; i < lines.length; i++) {
|
|
170
|
+
if (!/^\s*\|/.test(lines[i])) continue;
|
|
171
|
+
const header = splitRow(lines[i]);
|
|
172
|
+
const sep = lines[i + 1];
|
|
173
|
+
// A markdown table must have a separator row of dashes.
|
|
174
|
+
if (!sep || !/^\s*\|/.test(sep) || !isTableSeparator(sep)) continue;
|
|
175
|
+
const rows = [];
|
|
176
|
+
for (let j = i + 2; j < lines.length && /^\s*\|/.test(lines[j]); j++) {
|
|
177
|
+
const cells = splitRow(lines[j]);
|
|
178
|
+
// Skip a blank placeholder row.
|
|
179
|
+
if (cells.some((c) => c.length)) rows.push(cells);
|
|
180
|
+
if (rows.length >= MAX_TABLE_ROWS) break;
|
|
181
|
+
}
|
|
182
|
+
return { header, rows };
|
|
183
|
+
}
|
|
184
|
+
return null;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/* `## ` section titles, capped. Pure. */
|
|
188
|
+
function parseSections(src) {
|
|
189
|
+
const out = [];
|
|
190
|
+
for (const line of String(src).split(/\r?\n/)) {
|
|
191
|
+
const m = line.match(/^##\s+(.+?)\s*$/);
|
|
192
|
+
if (m && m[1] && m[1] !== "Table of contents") out.push(m[1]);
|
|
193
|
+
if (out.length >= MAX_SECTIONS) break;
|
|
194
|
+
}
|
|
195
|
+
return out;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/* Digest every session-start memory file: { file, exists, bytes, sections, table }. */
|
|
199
|
+
function memoryDigest(root) {
|
|
200
|
+
return MEMORY_FILES.map((file) => {
|
|
201
|
+
const abs = path.join(root, ".agents", "memory", file);
|
|
202
|
+
const src = safe(() => fs.readFileSync(abs, "utf8"), null);
|
|
203
|
+
if (src == null) return { file, exists: false };
|
|
204
|
+
return {
|
|
205
|
+
file,
|
|
206
|
+
exists: true,
|
|
207
|
+
bytes: Buffer.byteLength(src),
|
|
208
|
+
sections: parseSections(src),
|
|
209
|
+
table: parseFirstTable(src),
|
|
210
|
+
};
|
|
211
|
+
});
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/* Render the digest as a bounded block for the human/brief output. */
|
|
215
|
+
function renderMemoryDigest(memory) {
|
|
216
|
+
const lines = [];
|
|
217
|
+
for (const m of memory || []) {
|
|
218
|
+
if (!m.exists) continue;
|
|
219
|
+
if (m.sections && m.sections.length) lines.push(` ${m.file}: ${m.sections.join(" · ")}`);
|
|
220
|
+
if (m.table) {
|
|
221
|
+
lines.push(` ${m.table.header.join(" | ")}`);
|
|
222
|
+
for (const row of m.table.rows) lines.push(` ${row.join(" | ")}`);
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
return lines;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
/* The feature this session is working: explicit flag, else the board's single
|
|
230
|
+
* In-progress row, else the branch/dir name when it names a row. */
|
|
231
|
+
function inferFeature(explicit, branch, cwd, board) {
|
|
232
|
+
if (explicit) return String(explicit).toUpperCase();
|
|
233
|
+
const inprog = (board && board.inprogress) || [];
|
|
234
|
+
if (inprog.length === 1) return String(inprog[0].id || "").toUpperCase() || null;
|
|
235
|
+
const base = path.basename(String(cwd || "")).toUpperCase();
|
|
236
|
+
const m = base.match(/^F-\d+/) || String(branch || "").toUpperCase().match(/^F-\d+/);
|
|
237
|
+
return m ? m[0] : null;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/* Compare a feature id ("F-246") to a branch/dir name ("f-246", "F-246-...")
|
|
241
|
+
* ignoring case and separators. */
|
|
242
|
+
function normalizeId(s) {
|
|
243
|
+
return String(s || "").toLowerCase().replace(/[^a-z0-9]/g, "");
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/* The linked worktree a feature actually lives in, when the session root is a
|
|
247
|
+
* different checkout (the main tree). A /resume started in the main checkout
|
|
248
|
+
* otherwise reads the main tree's clean status + a green `tsc` and mistakes them
|
|
249
|
+
* for the feature's state; the work is uncommitted in the worktree. Returns
|
|
250
|
+
* `{ path, branch }` or null. `git` is injectable for tests. */
|
|
251
|
+
function featureWorktree(feature, root, git) {
|
|
252
|
+
if (!feature || typeof git !== "function") return null;
|
|
253
|
+
const want = normalizeId(feature);
|
|
254
|
+
if (!want) return null;
|
|
255
|
+
const out = safe(() => git(["worktree", "list", "--porcelain"]), null);
|
|
256
|
+
if (!out) return null;
|
|
257
|
+
let cur = null;
|
|
258
|
+
for (const line of String(out).split(/\r?\n/)) {
|
|
259
|
+
if (line.startsWith("worktree ")) {
|
|
260
|
+
cur = { path: line.slice("worktree ".length).trim(), branch: "" };
|
|
261
|
+
} else if (cur && line.startsWith("branch ")) {
|
|
262
|
+
cur.branch = line.slice("branch ".length).replace(/^refs\/heads\//, "").trim();
|
|
263
|
+
if (path.resolve(cur.path) === root) continue;
|
|
264
|
+
if (normalizeId(path.basename(cur.path)) === want || normalizeId(cur.branch) === want) {
|
|
265
|
+
return cur;
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
return null;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/* The whole orientation as a plain object. `deps` injects git/run for tests. */
|
|
273
|
+
function collectOrient(opts = {}) {
|
|
274
|
+
const root = path.resolve(opts.root || process.cwd());
|
|
275
|
+
const runGit = opts.git || gitRunner(root);
|
|
276
|
+
const runCmd = opts.run || null; // (argv[]) -> string|null, cwd=root
|
|
277
|
+
const readCheckpoint = opts.readCheckpoint || checkpoint.readCheckpoint;
|
|
278
|
+
|
|
279
|
+
const branch = safe(() => runGit(["rev-parse", "--abbrev-ref", "HEAD"]), null);
|
|
280
|
+
const head = safe(() => runGit(["rev-parse", "--short", "HEAD"]), null);
|
|
281
|
+
const status = safe(() => runGit(["status", "--porcelain"]), null);
|
|
282
|
+
const dirty = status == null ? null : status.split(/\r?\n/).filter(Boolean).length;
|
|
283
|
+
|
|
284
|
+
const board = runCmd ? boardSnapshot(root, (argv) => runCmd(argv)) : null;
|
|
285
|
+
const feature = inferFeature(opts.feature, branch, root, board);
|
|
286
|
+
const owned = ownedFor(root, feature);
|
|
287
|
+
// The feature may live in a linked worktree while this session is rooted in
|
|
288
|
+
// the main checkout. Surface it — a green main `tsc` is not the feature's.
|
|
289
|
+
const worktree = feature && checkoutKind(root) !== "linked" ? featureWorktree(feature, root, runGit) : null;
|
|
290
|
+
|
|
291
|
+
const ck = feature
|
|
292
|
+
? safe(() => readCheckpoint({ feature }), null)
|
|
293
|
+
: null;
|
|
294
|
+
const checkpointState = ck
|
|
295
|
+
? {
|
|
296
|
+
feature: ck.feature,
|
|
297
|
+
file: ck.file,
|
|
298
|
+
phase: ck.state && ck.state.phase,
|
|
299
|
+
nextAction: ck.state && ck.state.next_action,
|
|
300
|
+
count: ck.state && ck.state.checkpoint_count,
|
|
301
|
+
}
|
|
302
|
+
: null;
|
|
303
|
+
|
|
304
|
+
let cap = null;
|
|
305
|
+
try {
|
|
306
|
+
const s = capacity.sample(root);
|
|
307
|
+
const ev = capacity.evaluate(s, {});
|
|
308
|
+
cap = {
|
|
309
|
+
ok: ev.ok,
|
|
310
|
+
reasons: ev.reasons || [],
|
|
311
|
+
line: capacity.formatSummary(s).split("\n")[0],
|
|
312
|
+
serves: s.serves.filter((x) => x.alive).map((x) => x.name),
|
|
313
|
+
};
|
|
314
|
+
} catch (_) {
|
|
315
|
+
cap = null;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
return {
|
|
319
|
+
schema: SCHEMA,
|
|
320
|
+
root,
|
|
321
|
+
repo: {
|
|
322
|
+
kind: checkoutKind(root),
|
|
323
|
+
branch,
|
|
324
|
+
head,
|
|
325
|
+
dirty,
|
|
326
|
+
},
|
|
327
|
+
feature,
|
|
328
|
+
// Non-null when the feature's work is in a linked worktree and this session
|
|
329
|
+
// is rooted elsewhere (usually the main checkout): move before running tests.
|
|
330
|
+
featureWorktree: worktree ? { path: worktree.path, branch: worktree.branch } : null,
|
|
331
|
+
rootMismatch: Boolean(worktree),
|
|
332
|
+
board: board
|
|
333
|
+
? {
|
|
334
|
+
inprogress: (board.inprogress || []).map((r) => ({ id: r.id, task: r.task, handoff: r.handoff })),
|
|
335
|
+
nextQueued: (board.queued || []).slice(0, 3).map((r) => ({ id: r.id, task: r.task, dependsOn: r.dependsOn })),
|
|
336
|
+
}
|
|
337
|
+
: null,
|
|
338
|
+
ownedFiles: owned,
|
|
339
|
+
checkpoint: checkpointState,
|
|
340
|
+
capacity: cap,
|
|
341
|
+
memory: memoryDigest(root),
|
|
342
|
+
lastE2e: lastE2eRun(root),
|
|
343
|
+
nightly: latestNightly(root),
|
|
344
|
+
harnessVersion: harnessVersion(root),
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
function fmt(v, label) {
|
|
349
|
+
return v == null || v === "" ? `${label}: unavailable` : `${label}: ${v}`;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
function printHuman(o) {
|
|
353
|
+
const lines = [`Session orientation — ${o.root} (harness ${o.harnessVersion || "?"})`, ""];
|
|
354
|
+
if (o.rootMismatch) {
|
|
355
|
+
lines.push(
|
|
356
|
+
`!! ROOT MISMATCH — ${o.feature} lives in the linked worktree ${o.featureWorktree.path} (branch ${o.featureWorktree.branch || "?"})`,
|
|
357
|
+
` This session is rooted in ${o.root}; status/tsc/tests run here describe a DIFFERENT tree.`,
|
|
358
|
+
" Move the session there (session_move / `opencode -s <id> <worktree>`) and re-run orient before doing work.",
|
|
359
|
+
""
|
|
360
|
+
);
|
|
361
|
+
}
|
|
362
|
+
lines.push(`repo: ${o.repo.kind || "outside-git"} @ ${o.repo.branch || "?"} (HEAD ${o.repo.head || "?"})`);
|
|
363
|
+
lines.push(`dirty: ${o.repo.dirty == null ? "unavailable" : o.repo.dirty + " file(s)"}`);
|
|
364
|
+
lines.push(`feature: ${o.feature || "(none inferred — pass --feature <id>)"}`);
|
|
365
|
+
lines.push(`owned: ${o.ownedFiles || "unavailable"}`);
|
|
366
|
+
if (o.checkpoint) {
|
|
367
|
+
lines.push(`ckpt: ${path.basename(o.checkpoint.file)} · phase ${o.checkpoint.phase || "?"} · count ${o.checkpoint.count || 0}`);
|
|
368
|
+
if (o.checkpoint.nextAction) lines.push(`next: ${o.checkpoint.nextAction}`);
|
|
369
|
+
} else {
|
|
370
|
+
lines.push("ckpt: none (fresh work unit or feature has no checkpoint yet)");
|
|
371
|
+
}
|
|
372
|
+
if (o.board) {
|
|
373
|
+
const ip = o.board.inprogress.map((r) => r.id).join(", ") || "none";
|
|
374
|
+
lines.push(`board: In progress [${ip}]`);
|
|
375
|
+
if (o.board.nextQueued.length) {
|
|
376
|
+
lines.push(` next queued: ${o.board.nextQueued.map((r) => `${r.id} (${r.task || ""})`).join("; ")}`);
|
|
377
|
+
}
|
|
378
|
+
} else {
|
|
379
|
+
lines.push("board: unavailable (run `node scripts/backlog.js list` directly)");
|
|
380
|
+
}
|
|
381
|
+
if (o.capacity) {
|
|
382
|
+
lines.push(`capacity: ${o.capacity.ok ? "ok" : "EXCEEDED — " + o.capacity.reasons.join("; ")}`);
|
|
383
|
+
lines.push(` ${o.capacity.line}`);
|
|
384
|
+
lines.push(`serves: ${o.capacity.serves.join(", ") || "none running"}`);
|
|
385
|
+
} else {
|
|
386
|
+
lines.push("capacity: unavailable");
|
|
387
|
+
}
|
|
388
|
+
lines.push(
|
|
389
|
+
`last e2e: ${o.lastE2e ? `${o.lastE2e.failed || 0} failed / ${o.lastE2e.total != null ? o.lastE2e.total : "?"} (${o.lastE2e.at || "?"})` : "none recorded"}`
|
|
390
|
+
);
|
|
391
|
+
if (o.nightly) {
|
|
392
|
+
const n = o.nightly;
|
|
393
|
+
lines.push(
|
|
394
|
+
`nightly: ${(n.verdict || "?").toUpperCase()} (${n.at || "?"}) — ${n.failed} failing, ${n.reopened} reopened, ${n.added} new (${n.path})`
|
|
395
|
+
);
|
|
396
|
+
} else {
|
|
397
|
+
lines.push("nightly: none recorded (run `node scripts/nightly.js run`)");
|
|
398
|
+
}
|
|
399
|
+
const mem = renderMemoryDigest(o.memory);
|
|
400
|
+
if (mem.length) {
|
|
401
|
+
lines.push("memory digest (session-start reads — open a file only for detail):");
|
|
402
|
+
lines.push(...mem);
|
|
403
|
+
}
|
|
404
|
+
// The two capabilities the field consistently under-uses (2-week recon: 12
|
|
405
|
+
// `gates` calls vs 1539 hand-truncated gate invocations; 4 `where` calls vs
|
|
406
|
+
// 1129 shell greps): name them where the model actually reads, not only in a
|
|
407
|
+
// buried AGENTS.md bullet.
|
|
408
|
+
lines.push(
|
|
409
|
+
"tools: gates (run a tier: `gates --phase=quick`) · where (find a symbol: `where <term>`) · orient (re-orient) — prefer these over `npm run … | tail` and shell grep/find"
|
|
410
|
+
);
|
|
411
|
+
return lines.join("\n");
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
/* Compact single-block render for session-start injection: the actionable
|
|
415
|
+
* orientation facts only, bounded so it can ride a plugin nudge without
|
|
416
|
+
* dominating context. */
|
|
417
|
+
function printBrief(o) {
|
|
418
|
+
const lines = [];
|
|
419
|
+
lines.push(
|
|
420
|
+
`SESSION ORIENT — ${o.repo.kind || "outside-git"} @ ${o.repo.branch || "?"} (HEAD ${o.repo.head || "?"}, ${o.repo.dirty == null ? "?" : o.repo.dirty} dirty)`
|
|
421
|
+
);
|
|
422
|
+
lines.push(`harness ${o.harnessVersion || "?"} · root ${o.root}`);
|
|
423
|
+
if (o.rootMismatch) {
|
|
424
|
+
lines.push(
|
|
425
|
+
`!! ROOT MISMATCH — ${o.feature} lives in worktree ${o.featureWorktree.path}; move the session there BEFORE running anything (this root's tsc/status are a different tree).`
|
|
426
|
+
);
|
|
427
|
+
}
|
|
428
|
+
if (o.feature) lines.push(`feature ${o.feature}${o.ownedFiles ? ` · owns ${o.ownedFiles}` : ""}`);
|
|
429
|
+
if (o.checkpoint) lines.push(`checkpoint ${o.checkpoint.phase || "?"} · next: ${o.checkpoint.nextAction || "?"}`);
|
|
430
|
+
if (o.board) {
|
|
431
|
+
const ip = o.board.inprogress.map((r) => r.id).join(", ") || "none";
|
|
432
|
+
lines.push(`board In progress [${ip}]${o.board.nextQueued.length ? ` · next ${o.board.nextQueued.map((r) => r.id).join(", ")}` : ""}`);
|
|
433
|
+
}
|
|
434
|
+
if (o.capacity) lines.push(`capacity ${o.capacity.ok ? "ok" : "EXCEEDED: " + o.capacity.reasons.join("; ")} · serves ${o.capacity.serves.join(", ") || "none"}`);
|
|
435
|
+
if (o.lastE2e) lines.push(`last e2e ${o.lastE2e.failed || 0} failed / ${o.lastE2e.total != null ? o.lastE2e.total : "?"}`);
|
|
436
|
+
if (o.nightly) lines.push(`nightly ${(o.nightly.verdict || "?").toUpperCase()} — ${o.nightly.failed} failing, ${o.nightly.reopened} reopened, ${o.nightly.added} new`);
|
|
437
|
+
const mem = renderMemoryDigest(o.memory);
|
|
438
|
+
if (mem.length) {
|
|
439
|
+
lines.push("memory digest (open a file only for detail):");
|
|
440
|
+
lines.push(...mem);
|
|
441
|
+
}
|
|
442
|
+
lines.push("Proceed from the checkpoint/next; do not re-derive git/serve/capacity state by hand.");
|
|
443
|
+
lines.push("tools: gates (run a tier) · where (find a symbol) · orient — not `npm run … | tail` / shell grep.");
|
|
444
|
+
return lines.join("\n");
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
function parseArgs(argv) {
|
|
448
|
+
const out = { feature: null, json: false, brief: false, root: null, help: false };
|
|
449
|
+
for (let i = 0; i < argv.length; i++) {
|
|
450
|
+
const a = argv[i];
|
|
451
|
+
if (a === "--json") out.json = true;
|
|
452
|
+
else if (a === "--brief") out.brief = true;
|
|
453
|
+
else if (a === "--help" || a === "-h") out.help = true;
|
|
454
|
+
else if (a === "--feature") out.feature = argv[++i];
|
|
455
|
+
else if (a.startsWith("--feature=")) out.feature = a.slice("--feature=".length);
|
|
456
|
+
else if (a === "--root") out.root = argv[++i];
|
|
457
|
+
else if (a.startsWith("--root=")) out.root = a.slice("--root=".length);
|
|
458
|
+
}
|
|
459
|
+
return out;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
function main() {
|
|
463
|
+
const args = parseArgs(process.argv.slice(2));
|
|
464
|
+
if (args.help) {
|
|
465
|
+
console.log("Usage: node scripts/orient.js [--feature <id>] [--json] [--brief] [--root <dir>]");
|
|
466
|
+
return;
|
|
467
|
+
}
|
|
468
|
+
// Run board/backlog subprocesses relative to the resolved root.
|
|
469
|
+
const root = path.resolve(args.root || process.cwd());
|
|
470
|
+
const runCmd = (argv) => {
|
|
471
|
+
const r = spawnSync(process.execPath, argv, {
|
|
472
|
+
cwd: root,
|
|
473
|
+
encoding: "utf8",
|
|
474
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
475
|
+
timeout: 15000,
|
|
476
|
+
});
|
|
477
|
+
return r.status === 0 && typeof r.stdout === "string" ? r.stdout : null;
|
|
478
|
+
};
|
|
479
|
+
const o = collectOrient({ root, feature: args.feature, run: runCmd });
|
|
480
|
+
if (args.json) console.log(JSON.stringify(o, null, 2));
|
|
481
|
+
else if (args.brief) console.log(printBrief(o));
|
|
482
|
+
else console.log(printHuman(o));
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
if (require.main === module) {
|
|
486
|
+
try {
|
|
487
|
+
main();
|
|
488
|
+
} catch (e) {
|
|
489
|
+
console.error("orient: " + (e && e.message ? e.message : e));
|
|
490
|
+
process.exit(1);
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
|
|
494
|
+
module.exports = {
|
|
495
|
+
SCHEMA,
|
|
496
|
+
MEMORY_FILES,
|
|
497
|
+
collectOrient,
|
|
498
|
+
inferFeature,
|
|
499
|
+
featureWorktree,
|
|
500
|
+
checkoutKind,
|
|
501
|
+
ownedFor,
|
|
502
|
+
parseFirstTable,
|
|
503
|
+
parseSections,
|
|
504
|
+
memoryDigest,
|
|
505
|
+
renderMemoryDigest,
|
|
506
|
+
lastE2eRun,
|
|
507
|
+
latestNightly,
|
|
508
|
+
boardSnapshot,
|
|
509
|
+
gitRunner,
|
|
510
|
+
parseArgs,
|
|
511
|
+
printHuman,
|
|
512
|
+
printBrief,
|
|
513
|
+
fmt,
|
|
514
|
+
};
|