specdojo 0.4.1 → 0.4.2
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 +22 -0
- package/dist/commands/init.js +16 -0
- package/dist/dashboard/timeline-build.js +4 -151
- package/dist/exec/events.js +17 -6
- package/dist/exec/plans-core.js +16 -5
- package/dist/exec/plans-storage.js +11 -3
- package/dist/kata/kata.js +1 -1
- package/dist/register/core.js +3 -2
- package/dist/register/cross-project.js +134 -0
- package/dist/register/derivation.js +28 -7
- package/dist/register/item.js +26 -5
- package/dist/register/register.js +45 -28
- package/dist/schedule/strategy-generate-scope.js +2 -1
- package/dist/shared/catalog-files.js +31 -0
- package/dist/shared/lefthook-scaffold.js +177 -0
- package/dist/shared/specdojo-config.js +21 -4
- package/dist/shared/timeline-index.js +125 -0
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +4 -2
- package/docs/ja/specdojo/guides/quick-start-guide.md +23 -1
- package/docs/ja/specdojo/guides/register-operation-guide.md +12 -0
- package/docs/ja/specdojo/references/command-reference.md +39 -10
- package/docs/ja/specdojo/references/specdojo-config-reference.md +8 -5
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +5 -0
- package/package.json +1 -1
- package/templates/init-agent-members.yaml +3 -3
- package/templates/lefthook/tools/install-lefthook.mjs +46 -0
- package/templates/lefthook/tools/specdojo-pre-commit.mjs +207 -0
- package/templates/opencode/README.md +6 -1
- package/templates/opencode/agents/specdojo-orchestrator.md +1 -1
- /package/dist/{shared → kata}/yaml-schema-modeline.js +0 -0
|
@@ -18,6 +18,7 @@ import { applyItemUpdate, assertTerminalOperationAllowed, loadItemForUpdate, upd
|
|
|
18
18
|
import { generateDerivedViewFiles, loadRegisterItems, VALID_BUILD_SCOPES, writeDerivedViews, } from "./views.js";
|
|
19
19
|
import { specdojoRootDir } from "../shared/specdojo-config.js";
|
|
20
20
|
import { registerLifecyclePoolPath } from "./lifecycle-lock.js";
|
|
21
|
+
import { inCrossProjectWorktree, resolveCrossProjectMutationTarget } from "./cross-project.js";
|
|
21
22
|
export { PJR_ID_ALPHABET, PJR_ID_RE, TERMINAL_STATUSES_SET, toCell, VALID_PRIORITIES, VALID_DIFFICULTIES, VALID_STATUSES, VALID_TYPES, };
|
|
22
23
|
export { REGISTER_TOPIC_RE, VALID_TICKET_STATUSES, buildRegisterItemContent, extractTableHeading, findMarkdownReferenceFiles, generatePjrId, injectRegisterRows, parsePjrIndex, resolveRegisterPaths, } from "./core.js";
|
|
23
24
|
export { applyRegisterMigrationPlan, planRegisterMigration, } from "./migration.js";
|
|
@@ -135,38 +136,54 @@ function commitRegisterMutation(repoRoot, paths, command, result, preexisting, m
|
|
|
135
136
|
throw new Error(`Register commit incomplete: target paths remained dirty after hook stabilization:\n` +
|
|
136
137
|
remaining.map((path) => ` ${path}`).join("\n"));
|
|
137
138
|
}
|
|
139
|
+
async function runRegisterMutationInCurrentWorktree(command, opts, mutate, requireCleanRegister) {
|
|
140
|
+
const paths = resolveRegisterPaths(opts);
|
|
141
|
+
if (!opts.commit || opts.dryRun) {
|
|
142
|
+
mutate({ paths, assertCommitTargetsClean: () => undefined });
|
|
143
|
+
return;
|
|
144
|
+
}
|
|
145
|
+
const repoRoot = specdojoRootDir();
|
|
146
|
+
if (!paths.executionPath) {
|
|
147
|
+
throw new Error(`Execution path is not configured for project ${paths.projectId}`);
|
|
148
|
+
}
|
|
149
|
+
const mutex = new CrossProcessMutex(registerLifecyclePoolPath(paths.executionPath), {
|
|
150
|
+
actor: registerEventActor(opts),
|
|
151
|
+
label: `register ${command}`,
|
|
152
|
+
}, {
|
|
153
|
+
onWait: () => process.stdout.write("Waiting for the register lifecycle lock held by another operation\n"),
|
|
154
|
+
});
|
|
155
|
+
await mutex.runExclusive(() => {
|
|
156
|
+
const preexisting = new Set(worktreeStatusPaths(repoRoot));
|
|
157
|
+
if (requireCleanRegister) {
|
|
158
|
+
const registerPrefix = `${repoRelative(repoRoot, paths.projectRegisterPath)}/`;
|
|
159
|
+
const dirtyRegisterPaths = [...preexisting].filter((path) => path === registerPrefix.slice(0, -1) || path.startsWith(registerPrefix));
|
|
160
|
+
if (dirtyRegisterPaths.length > 0) {
|
|
161
|
+
throw new Error(`Cannot add to project ${paths.projectId} because its register has uncommitted changes:\n` +
|
|
162
|
+
dirtyRegisterPaths.map((path) => ` ${path}`).join("\n"));
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
const assertCommitTargetsClean = (targets) => {
|
|
166
|
+
const overlapping = targets
|
|
167
|
+
.map((target) => repoRelative(repoRoot, target))
|
|
168
|
+
.filter((target) => preexisting.has(target));
|
|
169
|
+
if (overlapping.length === 0)
|
|
170
|
+
return;
|
|
171
|
+
throw new Error(`Cannot use --commit because register targets already have uncommitted changes:\n` +
|
|
172
|
+
overlapping.map((path) => ` ${path}`).join("\n"));
|
|
173
|
+
};
|
|
174
|
+
const result = mutate({ paths, assertCommitTargetsClean });
|
|
175
|
+
rebuildRegisterViews(paths);
|
|
176
|
+
commitRegisterMutation(repoRoot, paths, command, result, preexisting, opts.message);
|
|
177
|
+
});
|
|
178
|
+
}
|
|
138
179
|
async function runRegisterMutation(command, opts, mutate) {
|
|
139
180
|
try {
|
|
140
|
-
const
|
|
141
|
-
if (
|
|
142
|
-
|
|
181
|
+
const crossProjectTarget = resolveCrossProjectMutationTarget(command, opts);
|
|
182
|
+
if (crossProjectTarget) {
|
|
183
|
+
await inCrossProjectWorktree(crossProjectTarget, () => runRegisterMutationInCurrentWorktree(command, opts, mutate, true));
|
|
143
184
|
return;
|
|
144
185
|
}
|
|
145
|
-
|
|
146
|
-
if (!paths.executionPath) {
|
|
147
|
-
throw new Error(`Execution path is not configured for project ${paths.projectId}`);
|
|
148
|
-
}
|
|
149
|
-
const mutex = new CrossProcessMutex(registerLifecyclePoolPath(paths.executionPath), {
|
|
150
|
-
actor: registerEventActor(opts),
|
|
151
|
-
label: `register ${command}`,
|
|
152
|
-
}, {
|
|
153
|
-
onWait: () => process.stdout.write("Waiting for the register lifecycle lock held by another operation\n"),
|
|
154
|
-
});
|
|
155
|
-
await mutex.runExclusive(() => {
|
|
156
|
-
const preexisting = new Set(worktreeStatusPaths(repoRoot));
|
|
157
|
-
const assertCommitTargetsClean = (targets) => {
|
|
158
|
-
const overlapping = targets
|
|
159
|
-
.map((target) => repoRelative(repoRoot, target))
|
|
160
|
-
.filter((target) => preexisting.has(target));
|
|
161
|
-
if (overlapping.length === 0)
|
|
162
|
-
return;
|
|
163
|
-
throw new Error(`Cannot use --commit because register targets already have uncommitted changes:\n` +
|
|
164
|
-
overlapping.map((path) => ` ${path}`).join("\n"));
|
|
165
|
-
};
|
|
166
|
-
const result = mutate({ paths, assertCommitTargetsClean });
|
|
167
|
-
rebuildRegisterViews(paths);
|
|
168
|
-
commitRegisterMutation(repoRoot, paths, command, result, preexisting, opts.message);
|
|
169
|
-
});
|
|
186
|
+
await runRegisterMutationInCurrentWorktree(command, opts, mutate, false);
|
|
170
187
|
}
|
|
171
188
|
catch (error) {
|
|
172
189
|
printCommandError(error);
|
|
@@ -2,8 +2,9 @@ import { existsSync } from "node:fs";
|
|
|
2
2
|
import { basename, join, relative, resolve } from "node:path";
|
|
3
3
|
import { collectResolvedDeliverables } from "../catalog/build.js";
|
|
4
4
|
import { resolveBasePath } from "../catalog/paths.js";
|
|
5
|
+
import { collectCatalogFilesByDomain } from "../shared/catalog-files.js";
|
|
5
6
|
import { readYaml } from "../shared/fs.js";
|
|
6
|
-
import {
|
|
7
|
+
import { loadTimelineIndex } from "../shared/timeline-index.js";
|
|
7
8
|
export function isRecord(value) {
|
|
8
9
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
9
10
|
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { existsSync, readdirSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { readYaml } from "./fs.js";
|
|
4
|
+
function isRecord(value) {
|
|
5
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
6
|
+
}
|
|
7
|
+
// 1 ドメインが dct-<domain>-<sub>.yaml のように複数ファイルへ分割されることがあるため、
|
|
8
|
+
// ファイル名ではなく各カタログの domain 値で突き合わせる。
|
|
9
|
+
export function collectCatalogFilesByDomain(catalogPath) {
|
|
10
|
+
const byDomain = new Map();
|
|
11
|
+
if (!existsSync(catalogPath))
|
|
12
|
+
return byDomain;
|
|
13
|
+
const files = readdirSync(catalogPath)
|
|
14
|
+
.filter((file) => /^dct-.+\.ya?ml$/.test(file))
|
|
15
|
+
.sort();
|
|
16
|
+
for (const file of files) {
|
|
17
|
+
const fullPath = join(catalogPath, file);
|
|
18
|
+
const parsed = readYaml(fullPath);
|
|
19
|
+
if (!isRecord(parsed))
|
|
20
|
+
continue;
|
|
21
|
+
const domain = parsed.domain;
|
|
22
|
+
if (typeof domain !== "string" || domain.trim().length === 0)
|
|
23
|
+
continue;
|
|
24
|
+
const group = byDomain.get(domain);
|
|
25
|
+
if (group)
|
|
26
|
+
group.push(fullPath);
|
|
27
|
+
else
|
|
28
|
+
byDomain.set(domain, [fullPath]);
|
|
29
|
+
}
|
|
30
|
+
return byDomain;
|
|
31
|
+
}
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
const REQUIRED_DEV_DEPENDENCIES = ["lefthook", "prettier", "markdownlint-cli"];
|
|
5
|
+
const REQUIRED_SCRIPTS = {
|
|
6
|
+
prepare: "node tools/install-lefthook.mjs",
|
|
7
|
+
"pre-commit": "lefthook run pre-commit",
|
|
8
|
+
};
|
|
9
|
+
const MARKDOWNLINT_CONFIG_FILES = [
|
|
10
|
+
".markdownlint.jsonc",
|
|
11
|
+
".markdownlint.json",
|
|
12
|
+
".markdownlint.yaml",
|
|
13
|
+
".markdownlint.yml",
|
|
14
|
+
".markdownlintrc",
|
|
15
|
+
];
|
|
16
|
+
const MARKDOWNLINT_CONFIG = `${JSON.stringify({
|
|
17
|
+
MD013: false,
|
|
18
|
+
MD024: false,
|
|
19
|
+
MD033: false,
|
|
20
|
+
MD036: false,
|
|
21
|
+
MD041: false,
|
|
22
|
+
MD060: false,
|
|
23
|
+
}, null, 2)}\n`;
|
|
24
|
+
const MARKDOWNLINT_IGNORE = [".claude/agents/", ".github/agents/", ".opencode/agents/", ""].join("\n");
|
|
25
|
+
function isRecord(value) {
|
|
26
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
27
|
+
}
|
|
28
|
+
function hasConfiguredPath(config, key) {
|
|
29
|
+
return Object.values(config.projects).some((project) => !!project[key]?.trim());
|
|
30
|
+
}
|
|
31
|
+
export function renderLefthookConfig(config) {
|
|
32
|
+
const commands = [
|
|
33
|
+
" prettier:",
|
|
34
|
+
' glob: "*.{md,yaml,yml}"',
|
|
35
|
+
" run: node tools/specdojo-pre-commit.mjs prettier {staged_files}",
|
|
36
|
+
" stage_fixed: true",
|
|
37
|
+
"",
|
|
38
|
+
" markdownlint:",
|
|
39
|
+
' glob: "*.md"',
|
|
40
|
+
" run: node tools/specdojo-pre-commit.mjs markdownlint {staged_files}",
|
|
41
|
+
];
|
|
42
|
+
if (hasConfiguredPath(config, "project_register_path")) {
|
|
43
|
+
commands.push("", " register-build:", " run: node tools/specdojo-pre-commit.mjs register-build", " stage_fixed: true");
|
|
44
|
+
}
|
|
45
|
+
if (hasConfiguredPath(config, "catalog_path")) {
|
|
46
|
+
commands.push("", " catalog-validate:", " run: node tools/specdojo-pre-commit.mjs catalog-validate");
|
|
47
|
+
}
|
|
48
|
+
return [
|
|
49
|
+
"# Generated by SpecDojo. Re-run `specdojo config scaffold --lefthook --force` to refresh.",
|
|
50
|
+
"pre-commit:",
|
|
51
|
+
" parallel: false",
|
|
52
|
+
" commands:",
|
|
53
|
+
...commands,
|
|
54
|
+
"",
|
|
55
|
+
].join("\n");
|
|
56
|
+
}
|
|
57
|
+
function detectIndent(content) {
|
|
58
|
+
const match = content.match(/^([\t ]+)\S/m);
|
|
59
|
+
if (!match)
|
|
60
|
+
return 2;
|
|
61
|
+
return match[1].includes("\t") ? "\t" : match[1].length;
|
|
62
|
+
}
|
|
63
|
+
function parsePackageJson(content, packageJsonPath) {
|
|
64
|
+
let value;
|
|
65
|
+
try {
|
|
66
|
+
value = JSON.parse(content);
|
|
67
|
+
}
|
|
68
|
+
catch (error) {
|
|
69
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
70
|
+
throw new Error(`Invalid JSON in ${packageJsonPath}: ${message}`);
|
|
71
|
+
}
|
|
72
|
+
if (!isRecord(value))
|
|
73
|
+
throw new Error(`Invalid JSON in ${packageJsonPath}: expected an object`);
|
|
74
|
+
return value;
|
|
75
|
+
}
|
|
76
|
+
async function requiredDependencyVersions(packageRoot) {
|
|
77
|
+
const sourcePath = path.join(packageRoot, "package.json");
|
|
78
|
+
const source = parsePackageJson(await readFile(sourcePath, "utf8"), sourcePath);
|
|
79
|
+
// prettier is a runtime dependency of SpecDojo itself, so versions are resolved from both fields.
|
|
80
|
+
const dependencies = {
|
|
81
|
+
...(isRecord(source.dependencies) ? source.dependencies : {}),
|
|
82
|
+
...(isRecord(source.devDependencies) ? source.devDependencies : {}),
|
|
83
|
+
};
|
|
84
|
+
return Object.fromEntries(REQUIRED_DEV_DEPENDENCIES.map((name) => {
|
|
85
|
+
const version = dependencies[name];
|
|
86
|
+
if (typeof version !== "string") {
|
|
87
|
+
throw new Error(`SpecDojo package.json (${sourcePath}) does not declare dependency or devDependency: ${name}`);
|
|
88
|
+
}
|
|
89
|
+
return [name, version];
|
|
90
|
+
}));
|
|
91
|
+
}
|
|
92
|
+
async function updatePackageJson(opts) {
|
|
93
|
+
const packageJsonPath = path.join(opts.repoRoot, "package.json");
|
|
94
|
+
const requiredDependencies = await requiredDependencyVersions(opts.packageRoot);
|
|
95
|
+
if (!existsSync(packageJsonPath)) {
|
|
96
|
+
process.stdout.write("Skipped package.json update (package.json not found). Add these entries after creating it:\n" +
|
|
97
|
+
`${JSON.stringify({ scripts: REQUIRED_SCRIPTS, devDependencies: requiredDependencies }, null, 2)}\n`);
|
|
98
|
+
return;
|
|
99
|
+
}
|
|
100
|
+
const content = await readFile(packageJsonPath, "utf8");
|
|
101
|
+
const packageJson = parsePackageJson(content, packageJsonPath);
|
|
102
|
+
if (packageJson.scripts !== undefined && !isRecord(packageJson.scripts)) {
|
|
103
|
+
throw new Error(`Invalid ${packageJsonPath}: scripts must be an object`);
|
|
104
|
+
}
|
|
105
|
+
if (packageJson.dependencies !== undefined && !isRecord(packageJson.dependencies)) {
|
|
106
|
+
throw new Error(`Invalid ${packageJsonPath}: dependencies must be an object`);
|
|
107
|
+
}
|
|
108
|
+
if (packageJson.devDependencies !== undefined && !isRecord(packageJson.devDependencies)) {
|
|
109
|
+
throw new Error(`Invalid ${packageJsonPath}: devDependencies must be an object`);
|
|
110
|
+
}
|
|
111
|
+
const scripts = isRecord(packageJson.scripts) ? packageJson.scripts : {};
|
|
112
|
+
const dependencies = isRecord(packageJson.dependencies) ? packageJson.dependencies : {};
|
|
113
|
+
const devDependencies = isRecord(packageJson.devDependencies) ? packageJson.devDependencies : {};
|
|
114
|
+
const scriptAdditions = Object.fromEntries(Object.entries(REQUIRED_SCRIPTS).filter(([name]) => !Object.hasOwn(scripts, name)));
|
|
115
|
+
const dependencyAdditions = Object.fromEntries(Object.entries(requiredDependencies).filter(([name]) => !Object.hasOwn(dependencies, name) && !Object.hasOwn(devDependencies, name)));
|
|
116
|
+
const additions = { scripts: scriptAdditions, devDependencies: dependencyAdditions };
|
|
117
|
+
process.stdout.write(`Planned package.json additions:\n${JSON.stringify(additions, null, 2)}\n`);
|
|
118
|
+
for (const name of Object.keys(REQUIRED_SCRIPTS)) {
|
|
119
|
+
if (Object.hasOwn(scripts, name)) {
|
|
120
|
+
process.stdout.write(`Skipped (script already exists): ${name} in package.json\n`);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
for (const name of REQUIRED_DEV_DEPENDENCIES) {
|
|
124
|
+
if (Object.hasOwn(dependencies, name) || Object.hasOwn(devDependencies, name)) {
|
|
125
|
+
process.stdout.write(`Skipped (dependency already exists): ${name} in package.json\n`);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
if (opts.dryRun ||
|
|
129
|
+
(Object.keys(scriptAdditions).length === 0 && Object.keys(dependencyAdditions).length === 0)) {
|
|
130
|
+
return;
|
|
131
|
+
}
|
|
132
|
+
packageJson.scripts = { ...scripts, ...scriptAdditions };
|
|
133
|
+
packageJson.devDependencies = { ...devDependencies, ...dependencyAdditions };
|
|
134
|
+
await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, detectIndent(content))}\n`, "utf8");
|
|
135
|
+
process.stdout.write("Updated: package.json\n");
|
|
136
|
+
}
|
|
137
|
+
async function writeScaffoldFile(sourcePath, destinationPath, destinationLabel, content, opts) {
|
|
138
|
+
if (existsSync(destinationPath) && !opts.force) {
|
|
139
|
+
process.stdout.write(`Skipped (already exists): ${destinationLabel}\n`);
|
|
140
|
+
return;
|
|
141
|
+
}
|
|
142
|
+
if (opts.dryRun) {
|
|
143
|
+
process.stdout.write(`[dry-run] would write: ${destinationLabel}\n`);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
await mkdir(path.dirname(destinationPath), { recursive: true });
|
|
147
|
+
if (sourcePath)
|
|
148
|
+
await copyFile(sourcePath, destinationPath);
|
|
149
|
+
else
|
|
150
|
+
await writeFile(destinationPath, content ?? "", "utf8");
|
|
151
|
+
process.stdout.write(`Written: ${destinationLabel}\n`);
|
|
152
|
+
}
|
|
153
|
+
async function writeMarkdownlintScaffold(opts) {
|
|
154
|
+
const existingConfig = MARKDOWNLINT_CONFIG_FILES.find((filename) => existsSync(path.join(opts.repoRoot, filename)));
|
|
155
|
+
if (existingConfig) {
|
|
156
|
+
process.stdout.write(`Skipped (markdownlint config already exists): ${existingConfig}\n`);
|
|
157
|
+
}
|
|
158
|
+
else {
|
|
159
|
+
await writeScaffoldFile(undefined, path.join(opts.repoRoot, ".markdownlint.jsonc"), ".markdownlint.jsonc", MARKDOWNLINT_CONFIG, { force: false, dryRun: opts.dryRun });
|
|
160
|
+
}
|
|
161
|
+
await writeScaffoldFile(undefined, path.join(opts.repoRoot, ".markdownlintignore"), ".markdownlintignore", MARKDOWNLINT_IGNORE, { force: false, dryRun: opts.dryRun });
|
|
162
|
+
}
|
|
163
|
+
export async function runLefthookScaffold(opts) {
|
|
164
|
+
const templateTools = path.join(opts.packageRoot, "templates", "lefthook", "tools");
|
|
165
|
+
await writeScaffoldFile(undefined, path.join(opts.repoRoot, "lefthook.yml"), "lefthook.yml", renderLefthookConfig(opts.config), opts);
|
|
166
|
+
await writeMarkdownlintScaffold(opts);
|
|
167
|
+
for (const filename of ["install-lefthook.mjs", "specdojo-pre-commit.mjs"]) {
|
|
168
|
+
await writeScaffoldFile(path.join(templateTools, filename), path.join(opts.repoRoot, "tools", filename), `tools/${filename}`, undefined, opts);
|
|
169
|
+
}
|
|
170
|
+
await updatePackageJson(opts);
|
|
171
|
+
if (!opts.dryRun) {
|
|
172
|
+
process.stdout.write("Next steps:\n" +
|
|
173
|
+
" 1. Run npm install and review the package.json additions shown above.\n" +
|
|
174
|
+
" 2. Run node tools/install-lefthook.mjs if an existing prepare script was kept.\n" +
|
|
175
|
+
" 3. Stage and commit lefthook.yml, markdownlint settings, tools/, and package.json.\n");
|
|
176
|
+
}
|
|
177
|
+
}
|
|
@@ -5,6 +5,7 @@ import { dump, load } from "./yaml.js";
|
|
|
5
5
|
import Ajv2020Module from "ajv/dist/2020.js";
|
|
6
6
|
import { runProviderScaffold, specdojoPackageRootDir } from "./provider-scaffold.js";
|
|
7
7
|
import { runWorkspaceScaffold } from "./workspace-scaffold.js";
|
|
8
|
+
import { runLefthookScaffold } from "./lefthook-scaffold.js";
|
|
8
9
|
import { ensureGitignore, formatGitignoreReport, gitignorePatternsForLayouts, } from "./specdojo-gitignore.js";
|
|
9
10
|
/** Default IANA time zone for register date derivation when run.register_date_timezone is unset. */
|
|
10
11
|
export const DEFAULT_REGISTER_DATE_TIMEZONE = "UTC";
|
|
@@ -535,6 +536,8 @@ function isValidProjectConfig(project) {
|
|
|
535
536
|
return false;
|
|
536
537
|
if (!isOmittedOrNonEmptyString(candidate.execution_path))
|
|
537
538
|
return false;
|
|
539
|
+
if (!isOmittedOrNonEmptyString(candidate.integration_branch))
|
|
540
|
+
return false;
|
|
538
541
|
if (candidate.project_context !== undefined &&
|
|
539
542
|
(!Array.isArray(candidate.project_context) ||
|
|
540
543
|
!candidate.project_context.every((ref) => typeof ref === "string" && ref.trim().length > 0))) {
|
|
@@ -562,7 +565,7 @@ export function loadConfig(configRootDir = specdojoRootDir()) {
|
|
|
562
565
|
for (const [projectId, project] of Object.entries(parsed.projects)) {
|
|
563
566
|
if (!isValidProjectConfig(project)) {
|
|
564
567
|
throw new Error(`Invalid .specdojo/specdojo.config.json: projects.${projectId} must omit ` +
|
|
565
|
-
`schedule_path/execution_path or set them to non-empty strings, ` +
|
|
568
|
+
`schedule_path/execution_path/integration_branch or set them to non-empty strings, ` +
|
|
566
569
|
`and project_context must be a string[] when present`);
|
|
567
570
|
}
|
|
568
571
|
}
|
|
@@ -676,17 +679,18 @@ export function registerConfigCommands(program) {
|
|
|
676
679
|
});
|
|
677
680
|
cfg
|
|
678
681
|
.command("scaffold")
|
|
679
|
-
.description("Scaffold
|
|
682
|
+
.description("Scaffold provider settings, a VS Code multi-root workspace, or Git hooks")
|
|
680
683
|
.option("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
|
|
681
684
|
.option("--workspace", "Generate VS Code multi-root workspace (<project-id>.code-workspace) from repos config", false)
|
|
685
|
+
.option("--lefthook", "Generate pre-commit hooks for SpecDojo repositories", false)
|
|
682
686
|
.option("--project <id>", "Target project ID for workspace scaffolding (defaults to current_project)")
|
|
683
687
|
.option("--force", "Overwrite existing files", false)
|
|
684
688
|
.option("--dry-run", "Show planned files without writing", false)
|
|
685
689
|
.option("--global", "Merge provider permissions into user-level settings (currently antigravity only)", false)
|
|
686
690
|
.action(async (opts) => {
|
|
687
691
|
try {
|
|
688
|
-
if (!opts.provider && !opts.workspace) {
|
|
689
|
-
throw new Error("Specify --provider <name
|
|
692
|
+
if (!opts.provider && !opts.workspace && !opts.lefthook) {
|
|
693
|
+
throw new Error("Specify --provider <name>, --workspace, or --lefthook to scaffold.");
|
|
690
694
|
}
|
|
691
695
|
if (opts.global && !opts.provider) {
|
|
692
696
|
throw new Error("--global requires --provider antigravity");
|
|
@@ -708,6 +712,19 @@ export function registerConfigCommands(program) {
|
|
|
708
712
|
dryRun: !!opts.dryRun,
|
|
709
713
|
});
|
|
710
714
|
}
|
|
715
|
+
if (opts.lefthook) {
|
|
716
|
+
const { configPath, config } = loadConfig();
|
|
717
|
+
if (!config) {
|
|
718
|
+
throw new Error(`No config found: ${configPath}. Run specdojo config init first.`);
|
|
719
|
+
}
|
|
720
|
+
await runLefthookScaffold({
|
|
721
|
+
packageRoot: specdojoPackageRootDir(),
|
|
722
|
+
repoRoot: specdojoRootDir(),
|
|
723
|
+
config,
|
|
724
|
+
force: !!opts.force,
|
|
725
|
+
dryRun: !!opts.dryRun,
|
|
726
|
+
});
|
|
727
|
+
}
|
|
711
728
|
}
|
|
712
729
|
catch (error) {
|
|
713
730
|
const message = error instanceof Error ? error.message : String(error);
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { readYaml } from "./fs.js";
|
|
2
|
+
import { normalizeDateOnly } from "./time.js";
|
|
3
|
+
const CATALOG_STATUSES = ["not_started", "draft", "primary"];
|
|
4
|
+
function isRecord(value) {
|
|
5
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
6
|
+
}
|
|
7
|
+
function readStringArray(value, field, errors) {
|
|
8
|
+
if (value === undefined)
|
|
9
|
+
return [];
|
|
10
|
+
if (!Array.isArray(value)) {
|
|
11
|
+
errors.push(`${field}: must be an array of strings`);
|
|
12
|
+
return [];
|
|
13
|
+
}
|
|
14
|
+
const result = [];
|
|
15
|
+
for (const item of value) {
|
|
16
|
+
if (typeof item !== "string" || item.trim().length === 0) {
|
|
17
|
+
errors.push(`${field}: must contain non-empty strings only`);
|
|
18
|
+
continue;
|
|
19
|
+
}
|
|
20
|
+
result.push(item);
|
|
21
|
+
}
|
|
22
|
+
return result;
|
|
23
|
+
}
|
|
24
|
+
function parseTrack(raw, index, errors) {
|
|
25
|
+
const where = `tracks[${index}]`;
|
|
26
|
+
if (!isRecord(raw)) {
|
|
27
|
+
errors.push(`${where}: must be an object`);
|
|
28
|
+
return null;
|
|
29
|
+
}
|
|
30
|
+
const track = raw.track;
|
|
31
|
+
if (typeof track !== "string" || track.trim().length === 0) {
|
|
32
|
+
errors.push(`${where}.track: required non-empty string`);
|
|
33
|
+
return null;
|
|
34
|
+
}
|
|
35
|
+
const domains = readStringArray(raw.domains, `${where}.domains`, errors);
|
|
36
|
+
if (domains.length === 0)
|
|
37
|
+
errors.push(`${where}.domains: required non-empty array`);
|
|
38
|
+
const catalogStatus = raw.catalog_status;
|
|
39
|
+
if (typeof catalogStatus !== "string" ||
|
|
40
|
+
!CATALOG_STATUSES.includes(catalogStatus)) {
|
|
41
|
+
errors.push(`${where}.catalog_status: must be one of ${CATALOG_STATUSES.join(" | ")}`);
|
|
42
|
+
return null;
|
|
43
|
+
}
|
|
44
|
+
const order = raw.order;
|
|
45
|
+
if (typeof order !== "number" || !Number.isInteger(order) || order < 1) {
|
|
46
|
+
errors.push(`${where}.order: must be an integer >= 1`);
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
if (raw.depends_on === undefined) {
|
|
50
|
+
errors.push(`${where}.depends_on: required (use [] when there is no prerequisite)`);
|
|
51
|
+
}
|
|
52
|
+
const dependsOn = readStringArray(raw.depends_on, `${where}.depends_on`, errors);
|
|
53
|
+
const estimate = raw.catalog_duration_estimate_days;
|
|
54
|
+
if (estimate !== undefined && (typeof estimate !== "number" || estimate <= 0)) {
|
|
55
|
+
errors.push(`${where}.catalog_duration_estimate_days: must be a number > 0`);
|
|
56
|
+
}
|
|
57
|
+
const parallelGroup = raw.parallel_group;
|
|
58
|
+
if (parallelGroup !== undefined && typeof parallelGroup !== "string") {
|
|
59
|
+
errors.push(`${where}.parallel_group: must be a string`);
|
|
60
|
+
}
|
|
61
|
+
const note = raw.note;
|
|
62
|
+
if (note !== undefined && typeof note !== "string") {
|
|
63
|
+
errors.push(`${where}.note: must be a string`);
|
|
64
|
+
}
|
|
65
|
+
return {
|
|
66
|
+
track,
|
|
67
|
+
domains,
|
|
68
|
+
catalog_status: catalogStatus,
|
|
69
|
+
...(typeof estimate === "number" ? { catalog_duration_estimate_days: estimate } : {}),
|
|
70
|
+
order,
|
|
71
|
+
...(typeof parallelGroup === "string" ? { parallel_group: parallelGroup } : {}),
|
|
72
|
+
depends_on: dependsOn,
|
|
73
|
+
...(typeof note === "string" ? { note } : {}),
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
export function loadTimelineIndex(filePath) {
|
|
77
|
+
const errors = [];
|
|
78
|
+
const parsed = readYaml(filePath);
|
|
79
|
+
if (!isRecord(parsed)) {
|
|
80
|
+
throw new Error(`${filePath}: invalid or empty YAML`);
|
|
81
|
+
}
|
|
82
|
+
const projectId = parsed.project_id;
|
|
83
|
+
if (typeof projectId !== "string" || projectId.trim().length === 0) {
|
|
84
|
+
errors.push(`project_id: required non-empty string`);
|
|
85
|
+
}
|
|
86
|
+
if (!Array.isArray(parsed.tracks) || parsed.tracks.length === 0) {
|
|
87
|
+
errors.push(`tracks: required non-empty array`);
|
|
88
|
+
return {
|
|
89
|
+
index: {
|
|
90
|
+
id: typeof parsed.id === "string" ? parsed.id : "",
|
|
91
|
+
project_id: typeof projectId === "string" ? projectId : "",
|
|
92
|
+
status: typeof parsed.status === "string" ? parsed.status : "",
|
|
93
|
+
tracks: [],
|
|
94
|
+
},
|
|
95
|
+
errors,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
const tracks = [];
|
|
99
|
+
parsed.tracks.forEach((raw, index) => {
|
|
100
|
+
const track = parseTrack(raw, index, errors);
|
|
101
|
+
if (track)
|
|
102
|
+
tracks.push(track);
|
|
103
|
+
});
|
|
104
|
+
// 計画開始日は YYYY-MM-DD に正規化する。不正な値はエラーとして報告し、未設定とみなす。
|
|
105
|
+
let plannedStartDate;
|
|
106
|
+
if (parsed.planned_start_date !== undefined && parsed.planned_start_date !== null) {
|
|
107
|
+
const normalized = normalizeDateOnly(parsed.planned_start_date);
|
|
108
|
+
if (!normalized) {
|
|
109
|
+
errors.push("planned_start_date: must be a YYYY-MM-DD date");
|
|
110
|
+
}
|
|
111
|
+
else {
|
|
112
|
+
plannedStartDate = normalized;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
return {
|
|
116
|
+
index: {
|
|
117
|
+
id: typeof parsed.id === "string" ? parsed.id : "",
|
|
118
|
+
project_id: typeof projectId === "string" ? projectId : "",
|
|
119
|
+
status: typeof parsed.status === "string" ? parsed.status : "",
|
|
120
|
+
tracks,
|
|
121
|
+
...(plannedStartDate !== undefined ? { planned_start_date: plannedStartDate } : {}),
|
|
122
|
+
},
|
|
123
|
+
errors,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
@@ -94,6 +94,8 @@ exec/results/<stem>-result.md
|
|
|
94
94
|
2. `--task <task-id>` がある場合は、`<stem> = <task-id>` とします。
|
|
95
95
|
3. task identity がない場合は、`<slug>-<UTC>-<rand>` のユニーク名を採番します。
|
|
96
96
|
|
|
97
|
+
`<rand>` は4バイト(16進8桁)です。同じプロセス内で slug・UTC秒・乱数がすべて重複した場合は、`<rand>-1`、`<rand>-2` のように連番を加えます。plan path から stem を読む処理は stem 全体を連結キーとして扱うため、従来の16進4桁の名前と連番付きの名前をどちらも読み取れます。
|
|
98
|
+
|
|
97
99
|
これにより、task 実行は固定名で扱い、schedule 非依存の実行は実行ごとの証跡を残せます。
|
|
98
100
|
|
|
99
101
|
### 2.4. deliverable指定の解決
|
|
@@ -199,10 +201,10 @@ specdojo exec archive --project <project-id> --task <task-id>
|
|
|
199
201
|
| 軽量実行(状態追跡なし) | `exec archive` で明示的に移動する |
|
|
200
202
|
| `exec run --archive-on-success` | 成功時に移動する |
|
|
201
203
|
|
|
202
|
-
固定名 plan を `done/` へ移動する場合は、UTC
|
|
204
|
+
固定名 plan を `done/` へ移動する場合は、UTC タイムスタンプと4バイトの乱数を付けます。同じ名前が既にある場合は、既存ファイルを上書きせず末尾に連番を加えます。
|
|
203
205
|
|
|
204
206
|
```text
|
|
205
|
-
exec/plans/done/<slug>-<UTC>-<rand
|
|
207
|
+
exec/plans/done/<slug>-<UTC>-<rand>[-<sequence>]-plan.md
|
|
206
208
|
```
|
|
207
209
|
|
|
208
210
|
不要な plan は `done/` へ移動せず削除してもかまいません。plan は catalog と schedule から再生成でき、result が記録として残るためです。
|
|
@@ -69,6 +69,7 @@ Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1
|
|
|
69
69
|
Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
|
|
70
70
|
Create a Dev Container? [y/N]: y <- y(Dev Container を作る。使わない場合は Enter)
|
|
71
71
|
Add the recommended Dev Container settings? [Y/n]: <- Enter(推奨 preset を入れる)
|
|
72
|
+
Create Git hooks with lefthook? [y/N]: <- Enter(この体験では作らない)
|
|
72
73
|
```
|
|
73
74
|
|
|
74
75
|
入力が不正な場合は理由が表示され、同じ質問だけがもう一度表示されます。たとえば provider に
|
|
@@ -227,7 +228,7 @@ npx specdojo init
|
|
|
227
228
|
```
|
|
228
229
|
|
|
229
230
|
`specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
|
|
230
|
-
exec・Dev Container の要否を順に質問し、Dev Container を選んだ場合だけ推奨 preset
|
|
231
|
+
exec・Dev Container・Git hook の要否を順に質問し、Dev Container を選んだ場合だけ推奨 preset を入れるか(既定は「はい」)を続けて質問します。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
|
|
231
232
|
明示した場合にだけ初期化時に作成します。選択に応じて設定、登録簿、人と
|
|
232
233
|
agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
|
|
233
234
|
作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
|
|
@@ -247,6 +248,7 @@ npx specdojo init --yes \
|
|
|
247
248
|
--provider claude,codex \
|
|
248
249
|
--exec \
|
|
249
250
|
--devcontainer \
|
|
251
|
+
--lefthook \
|
|
250
252
|
--dry-run
|
|
251
253
|
```
|
|
252
254
|
|
|
@@ -348,6 +350,26 @@ npx specdojo config scaffold --provider <name>
|
|
|
348
350
|
`<name>` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定します。従来の
|
|
349
351
|
`specdojo exec scaffold --provider <name>` も互換入口として利用できます。
|
|
350
352
|
|
|
353
|
+
commit 前に文書と SpecDojo の入力を検査する場合は、生成予定と `package.json` への追加内容を
|
|
354
|
+
dry-run で確認してから lefthook を配置します。
|
|
355
|
+
|
|
356
|
+
```bash
|
|
357
|
+
npx specdojo config scaffold --lefthook --dry-run
|
|
358
|
+
npx specdojo config scaffold --lefthook
|
|
359
|
+
npm install
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
生成した hook は、変更した Markdown と YAML だけを Prettier で整形し、変更した Markdown だけを
|
|
363
|
+
markdownlint で検査します。対象 project の `project_register_path` 配下を変更した場合は
|
|
364
|
+
`register build`、`catalog_path` 配下を変更した場合は `catalog validate` も実行します。
|
|
365
|
+
`catalog_path` がない構成には catalog の検査を生成せず、時間のかかるテストも pre-commit には
|
|
366
|
+
含めません。SpecDojo の文書が通る `.markdownlint.jsonc` と、provider の agent 定義を検査から外す
|
|
367
|
+
`.markdownlintignore` も生成します。既存の markdownlint 設定と ignore は `--force` を付けても保持します。
|
|
368
|
+
`lefthook.yml` と `tools/` の既存ファイルは `--force` なしでは上書きしません。
|
|
369
|
+
必要な npm script と devDependencies は書き込み前に表示し、同名の既存項目は `--force` を付けても
|
|
370
|
+
保持します。linked worktree または `node_modules` がない環境では installer が安全に skip するため、
|
|
371
|
+
primary worktree で `npm install` または `node tools/install-lefthook.mjs` を実行してください。
|
|
372
|
+
|
|
351
373
|
Antigravity CLI を無人実行する場合は、先に dry-run でユーザー設定へ追加する permission rule を確認し、明示的に適用します。このグローバル設定は利用者のすべてのリポジトリに効きます。通常の scaffold はユーザーディレクトリへ触れません。
|
|
352
374
|
|
|
353
375
|
```bash
|
|
@@ -83,6 +83,16 @@ specdojo register add --project <project-id> --type todo \
|
|
|
83
83
|
--title "在庫初期データの登録" --topic inventory-seed
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
+
別の project の作業ツリーから起票する場合は、対象 project と `--commit` を明示します。
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
specdojo register add --project prj-0002 --type todo \
|
|
90
|
+
--title "共通 API の変更を追跡する" --topic shared-api-change \
|
|
91
|
+
--from prj-0001:PJR-AB12 --commit
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
この経路は対象 project の `integration_branch`(省略時は `project/<project-id>/develop`)を開いている worktree を使い、無ければ一時 worktree を作ります。対象 project の名簿で `--by` を検証し、`register lifecycle` 枠の内側で起票、派生ビュー再生成、1 件の commit を行います。対象登録簿に未 commit 変更がある場合、または統合ブランチが存在しない場合は書き込みません。`--commit` のない別 project への起票と、別 project の項目に対する状態遷移は行えません。状態遷移は対象 project の作業ツリーで実行してください。
|
|
95
|
+
|
|
86
96
|
タイトルが日本語の場合は、内容を表す英語の `--topic` を小文字・ハイフン区切りで指定します。省略して `item` や日本語タイトル中の英単語だけが topic になった場合、`register add` は作成を続けたうえで警告します。警告後も、`register update --topic` で個票名と文書 ID を変更できます。成果物や kata(実践の型)を作成・修正する todo では、`--approach <approach> --target <doc-id>` を指定して進め方と対象を宣言できます(詳細は [exec運用ガイド](exec-operation-guide.md) の「register の todo から approach で成果物・kata を作る・直す手順」を参照してください)。
|
|
87
97
|
|
|
88
98
|
`--priority` は次の目安で付けます(省略時は `medium`)。
|
|
@@ -195,6 +205,8 @@ specdojo register close \
|
|
|
195
205
|
|
|
196
206
|
`--commit` は register の worktree 実行の記帳・統合と同じ `register lifecycle` 枠が空くまで待ち、枠の内側で記帳、`register build` 相当の検証・再生成、commit を順に行います。commit 対象はそのコマンドが新たに変更した個票・event・参照文書だけで、開始前からあるほかの未 commit 変更は残します。対象個票やevent自体に開始前の変更がある場合は、既存差分を混ぜないため書き込み前に停止します。既定の件名は `docs(register PJR-XXXX): <command> <title>` で、`-m <message>` または `--message <message>` で上書きできます。`--dry-run` と同時に指定した場合は表示だけを行い、枠の取得と commit は行いません。
|
|
197
207
|
|
|
208
|
+
別 project への起票では、対象登録簿全体が clean であることを追加で確認します。元の作業ツリーのブランチと HEAD は変更しません。
|
|
209
|
+
|
|
198
210
|
### 2.2. 個票の作成
|
|
199
211
|
|
|
200
212
|
すべての登録項目は、type 別のテンプレート(`pjr-todo-template.md` など `pjr-<type>-template.md`)から作る個票です。`register add` は個票の Frontmatter に構造化フィールドを書き込み、H1 と本文にタイトル・説明を置きます。
|