create-groundwork 0.0.0-stage → 3.1.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.
Files changed (73) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +63 -0
  4. package/README.md +81 -2
  5. package/dist/commands.js +294 -0
  6. package/dist/create.js +4 -0
  7. package/dist/engine.js +124 -0
  8. package/dist/groundwork.js +4 -0
  9. package/dist/profiles.js +77 -0
  10. package/dist/prompter.js +42 -0
  11. package/dist/scaffold.js +274 -0
  12. package/dist/text.js +31 -0
  13. package/package.json +48 -4
  14. package/template/.github/README.md +14 -0
  15. package/template/.github/pull_request_template.md +22 -0
  16. package/template/.github/workflows/docs-check.yml +23 -0
  17. package/template/AGENTS.md +88 -0
  18. package/template/BUILD.md +27 -0
  19. package/template/LICENSE.md +5 -0
  20. package/template/PROJECT.md +26 -0
  21. package/template/README.md +40 -0
  22. package/template/_gitignore +26 -0
  23. package/template/config/README.md +3 -0
  24. package/template/docs/README.md +53 -0
  25. package/template/docs/architecture/REPOSITORY_STRUCTURE.md +37 -0
  26. package/template/docs/architecture/SYSTEM_DESIGN.md +30 -0
  27. package/template/docs/architecture/adr/0000-template.md +28 -0
  28. package/template/docs/architecture/adr/README.md +11 -0
  29. package/template/docs/architecture/system-design/README.md +15 -0
  30. package/template/docs/engineering/SECURITY.md +22 -0
  31. package/template/docs/engineering/TEST_STRATEGY.md +33 -0
  32. package/template/docs/examples/EXAMPLE.md +56 -0
  33. package/template/docs/examples/PROFILES.md +75 -0
  34. package/template/docs/plans/README.md +10 -0
  35. package/template/docs/plans/_template/PLAN.md +39 -0
  36. package/template/docs/product/PRD.md +39 -0
  37. package/template/docs/product/SPEC.md +63 -0
  38. package/template/docs/product/specs/README.md +37 -0
  39. package/template/docs/product/specs/_template/SPEC.md +78 -0
  40. package/template/infrastructure/README.md +3 -0
  41. package/template/profiles/README.md +96 -0
  42. package/template/profiles/ai-systems/README.md +44 -0
  43. package/template/profiles/ai-systems/profile.json +35 -0
  44. package/template/profiles/ai-systems/templates/docs/ai-systems/EVALUATION.md +35 -0
  45. package/template/profiles/ai-systems/templates/docs/ai-systems/MODEL_INTEGRATION.md +37 -0
  46. package/template/profiles/ai-systems/templates/docs/ai-systems/RETRIEVAL.md +26 -0
  47. package/template/profiles/ai-systems/templates/docs/ai-systems/SAFETY.md +35 -0
  48. package/template/profiles/application/README.md +43 -0
  49. package/template/profiles/application/profile.json +47 -0
  50. package/template/profiles/application/templates/docs/application/RELEASES.md +28 -0
  51. package/template/profiles/backend-api/README.md +40 -0
  52. package/template/profiles/backend-api/profile.json +42 -0
  53. package/template/profiles/backend-api/templates/docs/backend-api/DATA.md +27 -0
  54. package/template/profiles/core/profile.json +74 -0
  55. package/template/profiles/core/templates/docs/architecture/contracts/README.md +11 -0
  56. package/template/profiles/core/templates/docs/architecture/system-design/01-system-overview.md +29 -0
  57. package/template/profiles/core/templates/docs/architecture/system-design/02-domain-and-state-model.md +27 -0
  58. package/template/profiles/core/templates/docs/architecture/system-design/03-behaviour-and-business-rules.md +29 -0
  59. package/template/profiles/core/templates/docs/architecture/system-design/04-architecture-and-interfaces.md +27 -0
  60. package/template/profiles/core/templates/docs/architecture/system-design/05-execution-and-resilience.md +30 -0
  61. package/template/profiles/core/templates/docs/architecture/system-design/06-operations-and-scalability.md +27 -0
  62. package/template/profiles/core/templates/docs/architecture/system-design/07-ui-and-interaction-mapping.md +35 -0
  63. package/template/profiles/core/templates/docs/design/DESIGN.md +202 -0
  64. package/template/profiles/web/README.md +41 -0
  65. package/template/profiles/web/profile.json +34 -0
  66. package/template/profiles/web/templates/docs/web/CONTENT.md +39 -0
  67. package/template/profiles/web/templates/docs/web/SEO.md +35 -0
  68. package/template/scaffold-manifest.json +77 -0
  69. package/template/scripts/README.md +29 -0
  70. package/template/scripts/check_docs.py +989 -0
  71. package/template/scripts/groundwork.py +716 -0
  72. package/template/src/README.md +3 -0
  73. package/template/tests/README.md +3 -0
package/dist/engine.js ADDED
@@ -0,0 +1,124 @@
1
+ // Bridge to the Groundwork engine: the Python scripts that ship inside every
2
+ // project (scripts/groundwork.py and scripts/check_docs.py). All profile
3
+ // rules, generation and validation live there, so the CLI and the plain
4
+ // Python workflow always behave the same. This module finds Python, runs
5
+ // those scripts, and works out which project a command applies to.
6
+ import { spawnSync } from "node:child_process";
7
+ import { existsSync, readFileSync, realpathSync } from "node:fs";
8
+ import { dirname, join, resolve } from "node:path";
9
+ import { fileURLToPath } from "node:url";
10
+ export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
11
+ export const TEMPLATE_ROOT = join(PACKAGE_ROOT, "template");
12
+ export const VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
13
+ /** An error shown to the user as-is, with the exit code to use. */
14
+ export class GroundworkError extends Error {
15
+ exitCode;
16
+ constructor(message, exitCode = 1) {
17
+ super(message);
18
+ this.exitCode = exitCode;
19
+ }
20
+ }
21
+ // --- Python -------------------------------------------------------------------
22
+ const MIN_PYTHON = [3, 9];
23
+ let cachedPython;
24
+ /** The first Python 3.9+ found: $GROUNDWORK_PYTHON, python3, python, or (Windows) py -3. */
25
+ export function findPython() {
26
+ if (cachedPython)
27
+ return cachedPython;
28
+ const fromEnv = process.env.GROUNDWORK_PYTHON;
29
+ const candidates = fromEnv
30
+ ? [[fromEnv, []]]
31
+ : [["python3", []], ["python", []], ...(process.platform === "win32" ? [["py", ["-3"]]] : [])];
32
+ const tried = [];
33
+ for (const [command, args] of candidates) {
34
+ const probe = spawnSync(command, [...args, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"], {
35
+ encoding: "utf8",
36
+ });
37
+ if (probe.error || probe.status !== 0) {
38
+ tried.push(`${[command, ...args].join(" ")} (not found)`);
39
+ continue;
40
+ }
41
+ const version = probe.stdout.trim();
42
+ const [major = 0, minor = 0] = version.split(".").map(Number);
43
+ if (major > MIN_PYTHON[0] || (major === MIN_PYTHON[0] && minor >= MIN_PYTHON[1])) {
44
+ cachedPython = { command, args, version };
45
+ return cachedPython;
46
+ }
47
+ tried.push(`${command} (Python ${version} is too old)`);
48
+ }
49
+ throw new GroundworkError([
50
+ `Groundwork needs Python ${MIN_PYTHON.join(".")} or newer, and none was found.`,
51
+ "Its checks are plain Python scripts that ship inside every project, so any project can be checked in CI without Node.",
52
+ `Tried: ${tried.join(", ")}.`,
53
+ "Install Python from https://www.python.org/downloads/ or your package manager,",
54
+ "or set GROUNDWORK_PYTHON to the path of a Python 3 executable.",
55
+ ].join("\n"));
56
+ }
57
+ /** Run one of a project's scripts. "inherit" streams its output straight to the user. */
58
+ export function runScript(root, script, args, mode) {
59
+ const python = findPython();
60
+ const result = spawnSync(python.command, [...python.args, "-I", join(root, "scripts", script), ...args], {
61
+ cwd: root,
62
+ encoding: "utf8",
63
+ stdio: mode === "inherit" ? "inherit" : "pipe",
64
+ });
65
+ if (result.error)
66
+ throw new GroundworkError(`Could not run ${script}: ${result.error.message}`);
67
+ return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
68
+ }
69
+ /** Run groundwork.py with --json and parse its single JSON object. */
70
+ export function runEngine(root, args) {
71
+ const result = runScript(root, "groundwork.py", [...args, "--json"], "capture");
72
+ try {
73
+ return JSON.parse(result.stdout);
74
+ }
75
+ catch {
76
+ const detail = (result.stderr || result.stdout).trim();
77
+ throw new GroundworkError(`groundwork.py ${args[0]} failed unexpectedly:\n${detail}`);
78
+ }
79
+ }
80
+ function same(a, b) {
81
+ try {
82
+ return realpathSync(a) === realpathSync(b);
83
+ }
84
+ catch {
85
+ return false;
86
+ }
87
+ }
88
+ /**
89
+ * A folder is a Groundwork project only when it has the checker script and
90
+ * either a .groundwork/config.json or a scaffold-manifest.json named
91
+ * "Groundwork" — never just because some files look familiar.
92
+ */
93
+ export function isProject(dir) {
94
+ if (!existsSync(join(dir, "scripts", "check_docs.py")))
95
+ return false;
96
+ if (existsSync(join(dir, ".groundwork", "config.json")))
97
+ return true;
98
+ try {
99
+ const manifest = JSON.parse(readFileSync(join(dir, "scaffold-manifest.json"), "utf8"));
100
+ return manifest?.name === "Groundwork" && Array.isArray(manifest.files);
101
+ }
102
+ catch {
103
+ return false;
104
+ }
105
+ }
106
+ /** The nearest Groundwork project at or above `start`, or null. */
107
+ export function findProject(start = process.cwd()) {
108
+ let dir = resolve(start);
109
+ for (;;) {
110
+ if (isProject(dir)) {
111
+ const engine = join(dir, "scripts", "groundwork.py");
112
+ return {
113
+ root: dir,
114
+ hasEngine: existsSync(engine),
115
+ hasJsonEngine: existsSync(engine) && readFileSync(engine, "utf8").includes('"--json"'),
116
+ isBundledTemplate: same(dir, TEMPLATE_ROOT),
117
+ };
118
+ }
119
+ const parent = dirname(dir);
120
+ if (parent === dir)
121
+ return null;
122
+ dir = parent;
123
+ }
124
+ }
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ // Entry point for `groundwork <command> [options]`.
3
+ import { main, runGroundwork } from "./commands.js";
4
+ await main(() => runGroundwork(process.argv.slice(2)));
@@ -0,0 +1,77 @@
1
+ // Show profiles exactly as their manifests describe them. Nothing here
2
+ // decides anything: the manifests are the source of truth, and the engine
3
+ // enforces the rules.
4
+ import { bold, bullet, dim, wrap } from "./text.js";
5
+ export const CORE = "core";
6
+ function list(items, last = "or") {
7
+ if (items.length <= 1)
8
+ return items.join("");
9
+ return `${items.slice(0, -1).join(", ")} ${last} ${items.at(-1)}`;
10
+ }
11
+ /** Human-readable dependency lines, using profile names. */
12
+ export function describeRequires(profile, all) {
13
+ const name = (id) => all.find((p) => p.id === id)?.name ?? id;
14
+ return (profile.requires ?? []).map((entry) => typeof entry === "string" ? name(entry) : entry.length === 1 ? name(entry[0]) : `one of ${list(entry.map(name))}`);
15
+ }
16
+ /** The first sentence of a purpose, for short hints. */
17
+ export function summary(profile) {
18
+ const match = profile.purpose.match(/^.*?[.:](\s|$)/);
19
+ return (match ? match[0] : profile.purpose).trim().replace(/[.:]$/, "");
20
+ }
21
+ export function formatProfileList(profiles, source) {
22
+ const out = [`${bold("Groundwork profiles")} ${dim(`(from ${source})`)}`, ""];
23
+ for (const profile of profiles) {
24
+ const core = profile.id === CORE;
25
+ out.push(` ${bold(profile.id)} — ${profile.name}${core ? dim(" (always active)") : ""}`);
26
+ out.push(wrap(profile.purpose, " "));
27
+ if (!core) {
28
+ out.push(` Use when:`);
29
+ for (const item of profile.use_when ?? [])
30
+ out.push(bullet(item, " "));
31
+ out.push(` Not when:`);
32
+ for (const item of profile.not_when ?? [])
33
+ out.push(bullet(item, " "));
34
+ const requires = describeRequires(profile, profiles);
35
+ if (requires.length)
36
+ out.push(` Requires: ${requires.join("; ")}`);
37
+ if (profile.incompatible_with?.length)
38
+ out.push(` Incompatible with: ${profile.incompatible_with.join(", ")}`);
39
+ }
40
+ out.push("");
41
+ }
42
+ out.push("Choose by what the system does, not by the technology it uses.");
43
+ out.push(`Details of one profile: ${bold("groundwork profiles <id>")}`);
44
+ return out.join("\n");
45
+ }
46
+ export function formatProfile(profile, all, source) {
47
+ const core = profile.id === CORE;
48
+ const out = [`${bold(profile.name)} ${dim(`(${profile.id}${core ? ", always active" : ""}) — from ${source}`)}`, ""];
49
+ out.push(wrap(profile.purpose), "");
50
+ if (!core) {
51
+ out.push(bold("When to use it"));
52
+ for (const item of profile.use_when ?? [])
53
+ out.push(bullet(item));
54
+ out.push("", bold("When not to use it"));
55
+ for (const item of profile.not_when ?? [])
56
+ out.push(bullet(item));
57
+ out.push("", bold("Dependencies"));
58
+ const requires = describeRequires(profile, all);
59
+ out.push(requires.length ? requires.map((r) => ` - Requires ${r}`).join("\n") : " - None");
60
+ if (profile.incompatible_with?.length)
61
+ out.push(` - Incompatible with ${profile.incompatible_with.join(", ")}`);
62
+ out.push("");
63
+ }
64
+ const required = profile.documents.filter((d) => d.required);
65
+ const optional = profile.documents.filter((d) => !d.required);
66
+ out.push(bold("Required documents"));
67
+ out.push(required.length ? required.map((d) => ` - ${d.path}`).join("\n") : " - None");
68
+ out.push("", bold("Optional documents") + dim(" (create one when its condition holds: groundwork add <path>)"));
69
+ out.push(optional.length ? optional.map((d) => bullet(`${d.path}: ${d.when}`)).join("\n") : " - None");
70
+ if (!core) {
71
+ out.push("", bold("Engineering checks") + dim(" (rows in the AGENTS.md tooling table)"));
72
+ const checks = profile.checks ?? [];
73
+ out.push(checks.length ? checks.map((c) => bullet(`${c.name}: ${c.what}`)).join("\n") : " - None");
74
+ }
75
+ out.push("", `Standards and agent instructions: ${profile.readme}`);
76
+ return out.join("\n");
77
+ }
@@ -0,0 +1,42 @@
1
+ // The interactive prompts the creation wizard uses. The wizard depends only
2
+ // on the Prompter interface, so tests can drive it with scripted answers;
3
+ // the real implementation uses @clack/prompts.
4
+ import * as clack from "@clack/prompts";
5
+ /** The person cancelled (Ctrl+C or Escape). */
6
+ export class Cancelled extends Error {
7
+ constructor() {
8
+ super("Cancelled — nothing was created.");
9
+ }
10
+ }
11
+ function answer(value) {
12
+ if (clack.isCancel(value))
13
+ throw new Cancelled();
14
+ return value;
15
+ }
16
+ export const clackPrompter = {
17
+ intro: (title) => clack.intro(title),
18
+ outro: (message) => clack.outro(message),
19
+ note: (message, title) => clack.note(message, title),
20
+ info: (message) => clack.log.info(message),
21
+ warn: (message) => clack.log.warn(message),
22
+ error: (message) => clack.log.error(message),
23
+ success: (message) => clack.log.success(message),
24
+ text: async ({ message, initialValue, placeholder, validate }) => answer(await clack.text({
25
+ message,
26
+ initialValue,
27
+ placeholder,
28
+ validate: validate ? (value) => validate(value ?? "") : undefined,
29
+ })),
30
+ confirm: async ({ message, initialValue }) => answer(await clack.confirm({ message, initialValue })),
31
+ select: async ({ message, options, initialValue }) => answer(await clack.select({ message, options: options, initialValue })),
32
+ multiselect: async ({ message, options, initialValues }) => answer(await clack.multiselect({
33
+ message,
34
+ options: options,
35
+ initialValues,
36
+ required: false,
37
+ })),
38
+ spinner: () => {
39
+ const spin = clack.spinner();
40
+ return { start: (message) => spin.start(message), stop: (message) => spin.stop(message) };
41
+ },
42
+ };
@@ -0,0 +1,274 @@
1
+ // Creating a new project: the interactive wizard and the non-interactive
2
+ // path. Both end in the same engine call (`groundwork.py new`), which
3
+ // validates the selection, builds the project in a staging folder and moves
4
+ // it into place only if everything succeeded.
5
+ import { existsSync, readdirSync, statSync } from "node:fs";
6
+ import { dirname, relative, resolve } from "node:path";
7
+ import { GroundworkError, runEngine, runScript, TEMPLATE_ROOT, VERSION, } from "./engine.js";
8
+ import { CORE, describeRequires, summary } from "./profiles.js";
9
+ import { bold, green, red } from "./text.js";
10
+ export function slug(name) {
11
+ return (name
12
+ .toLowerCase()
13
+ .replace(/[^a-z0-9]+/g, "-")
14
+ .replace(/^-+|-+$/g, "") || "project");
15
+ }
16
+ function display(path) {
17
+ const rel = relative(process.cwd(), path);
18
+ return rel && !rel.startsWith("..") ? `./${rel}` : path;
19
+ }
20
+ export function loadProfiles() {
21
+ const list = runEngine(TEMPLATE_ROOT, ["list"]);
22
+ if (!list.ok)
23
+ throw new GroundworkError(`The bundled Groundwork template is invalid:\n${(list.errors ?? []).join("\n")}`);
24
+ return list.profiles;
25
+ }
26
+ function generate(answers, dryRun) {
27
+ const ids = answers.profiles.length ? answers.profiles : ["none"];
28
+ return runEngine(TEMPLATE_ROOT, [
29
+ "new",
30
+ answers.destination,
31
+ `--name=${answers.name}`,
32
+ `--description=${answers.description}`,
33
+ ...(dryRun ? ["--dry-run"] : []),
34
+ "--profiles",
35
+ ...ids,
36
+ ]);
37
+ }
38
+ // --- Validation used while prompting (the engine re-checks everything) --------
39
+ function checkName(value) {
40
+ if (!value.trim())
41
+ return "Enter a project name.";
42
+ if (value.length > 100)
43
+ return "Keep it to 100 characters or fewer.";
44
+ if (value.includes("{{") || value.includes("}}"))
45
+ return "The name can't contain {{ or }}.";
46
+ return undefined;
47
+ }
48
+ function checkDestination(value) {
49
+ if (!value.trim())
50
+ return "Enter a folder.";
51
+ const path = resolve(value);
52
+ if (existsSync(path) && (!statSync(path).isDirectory() || readdirSync(path).length > 0)) {
53
+ return "That folder already exists and isn't empty. Groundwork never overwrites files — choose another.";
54
+ }
55
+ if (!existsSync(dirname(path)))
56
+ return `${dirname(path)} doesn't exist. Create it first, or choose another folder.`;
57
+ return undefined;
58
+ }
59
+ // --- Summaries -----------------------------------------------------------------
60
+ function profileNames(ids, all) {
61
+ return ids.map((id) => all.find((p) => p.id === id)?.name ?? id);
62
+ }
63
+ function reviewText(answers, plan, all) {
64
+ const init = plan.init;
65
+ const created = init.documents.filter((d) => d.action === "create").map((d) => d.path);
66
+ const lines = [
67
+ `Project: ${answers.name}`,
68
+ ...(answers.description ? [`Description: ${answers.description}`] : []),
69
+ `Folder: ${display(answers.destination)}`,
70
+ `Profiles: ${["Core (always)", ...profileNames(init.profiles, all)].join(", ")}`,
71
+ ];
72
+ const deps = init.profiles.flatMap((id) => {
73
+ const profile = all.find((p) => p.id === id);
74
+ return profile ? describeRequires(profile, all).map((r) => `${profile.name} requires ${r} — satisfied`) : [];
75
+ });
76
+ if (deps.length)
77
+ lines.push("", "Dependencies:", ...deps.map((d) => ` ✓ ${d}`));
78
+ lines.push("", `Files: ${plan.files} from Groundwork (core documents, profiles, scripts)${created.length ? ", plus:" : ""}`);
79
+ lines.push(...created.map((path) => ` + ${path}`));
80
+ const checks = init.checks;
81
+ if (checks.length) {
82
+ lines.push("", "Engineering checks added to AGENTS.md:", ...checks.map((c) => ` - ${c.name} (${c.profile})`));
83
+ }
84
+ if (init.optional.length) {
85
+ lines.push("", "Optional documents, for later (groundwork add <path>):", ...init.optional.map((o) => ` - ${o.path}`));
86
+ }
87
+ return lines.join("\n");
88
+ }
89
+ function completionText(answers, result, all, validated, check) {
90
+ const created = result.init.documents.filter((d) => d.action === "create").map((d) => d.path);
91
+ const names = profileNames(result.init.profiles, all);
92
+ const lines = [
93
+ `Project: ${answers.name}`,
94
+ "",
95
+ "Active profiles:",
96
+ ...(names.length ? names.map((n) => ` - ${n}`) : [" - none (Groundwork Core only)"]),
97
+ "",
98
+ `Generated: ${result.files} files from Groundwork (core documents, profiles, scripts)${created.length ? ", plus:" : ""}`,
99
+ ...created.map((path) => ` + ${path}`),
100
+ "",
101
+ "Validation:",
102
+ ];
103
+ if (validated) {
104
+ lines.push(` ${green("✓")} Profile selection, dependencies and document ownership`, ` ${green("✓")} Required documents present`, ` ${green("✓")} Manifest, requirement IDs and links`);
105
+ }
106
+ else {
107
+ lines.push(` ${red("✗")} The documentation check reported problems:`, ...check.trim().split("\n").map((l) => ` ${l}`));
108
+ }
109
+ lines.push("", "Next steps:", ` cd ${display(result.destination)}`, " groundwork validate (or: python3 scripts/check_docs.py)", " Fill in PROJECT.md, then docs/product/PRD.md, and read profiles/README.md.");
110
+ return lines.join("\n");
111
+ }
112
+ function finish(answers, result, all) {
113
+ const check = runScript(result.destination, "check_docs.py", [], "capture");
114
+ return { ok: check.status === 0, text: completionText(answers, result, all, check.status === 0, check.stdout + check.stderr) };
115
+ }
116
+ // --- Interactive wizard --------------------------------------------------------------
117
+ async function chooseProfiles(p, all, current) {
118
+ const selectable = all.filter((profile) => profile.id !== CORE);
119
+ let recommended = current;
120
+ if (!current.length) {
121
+ const mode = await p.select({
122
+ message: "How would you like to choose profiles?",
123
+ options: [
124
+ { value: "guided", label: "Guide me", hint: `one question per profile (${selectable.length})` },
125
+ { value: "direct", label: "I know which profiles I need" },
126
+ ],
127
+ initialValue: "guided",
128
+ });
129
+ if (mode === "guided") {
130
+ p.info("Choose by what the system must do and keep doing — not by the technology it uses.");
131
+ recommended = [];
132
+ for (const profile of selectable) {
133
+ const guidance = [
134
+ "Use it when:",
135
+ ...(profile.use_when ?? []).map((s) => ` • ${s}`),
136
+ "Not when:",
137
+ ...(profile.not_when ?? []).map((s) => ` • ${s}`),
138
+ ].join("\n");
139
+ p.note(guidance, `${profile.name} — ${summary(profile)}`);
140
+ if (await p.confirm({ message: `Does this describe a responsibility of your system?`, initialValue: false })) {
141
+ recommended.push(profile.id);
142
+ }
143
+ }
144
+ }
145
+ }
146
+ return p.multiselect({
147
+ message: "Select profiles (space to toggle, enter to confirm; none selected = Groundwork Core only)",
148
+ options: selectable.map((profile) => {
149
+ const requires = describeRequires(profile, all);
150
+ return {
151
+ value: profile.id,
152
+ label: profile.name,
153
+ hint: [summary(profile), ...requires.map((r) => `requires ${r}`)].join(" · "),
154
+ };
155
+ }),
156
+ initialValues: recommended,
157
+ });
158
+ }
159
+ async function wizard(options, p, all) {
160
+ p.intro(` Groundwork ${VERSION} `);
161
+ const name = options.name ??
162
+ (await p.text({
163
+ message: "Project name",
164
+ initialValue: options.dir ? options.dir.split(/[\\/]/).filter(Boolean).at(-1) : undefined,
165
+ placeholder: "parkmate",
166
+ validate: checkName,
167
+ }));
168
+ const description = options.description ??
169
+ (await p.text({ message: "One-line description (optional)", placeholder: "Parking management platform" }));
170
+ const destination = resolve(options.dir ??
171
+ (await p.text({ message: "Where should it go?", initialValue: `./${slug(name)}`, validate: checkDestination })));
172
+ const problem = checkName(name) ?? checkDestination(destination);
173
+ if (problem) {
174
+ p.error(problem);
175
+ return null;
176
+ }
177
+ let profiles = options.profiles ? options.profiles.filter((id) => id !== "none") : [];
178
+ let skipSelection = options.profiles !== undefined;
179
+ for (;;) {
180
+ if (!skipSelection)
181
+ profiles = await chooseProfiles(p, all, profiles);
182
+ skipSelection = false;
183
+ const answers = { name: name.trim(), description: description.trim(), destination, profiles };
184
+ const plan = generate(answers, true);
185
+ if (!plan.ok) {
186
+ // Selection problems (unknown IDs, dependencies, conflicts) go back to
187
+ // selection; anything else stops here.
188
+ const errors = plan.errors ?? [];
189
+ for (const error of errors)
190
+ p.error(error.replace(/^PROJECT\.md: /, ""));
191
+ if (!errors.length || !errors.every((e) => e.startsWith("PROJECT.md: ")))
192
+ return null;
193
+ continue;
194
+ }
195
+ p.note(reviewText(answers, plan, all), "Review");
196
+ if (options.yes)
197
+ return answers;
198
+ const next = await p.select({
199
+ message: options.dryRun ? "Dry run — nothing will be written. Continue?" : "Create the project?",
200
+ options: [
201
+ { value: "create", label: options.dryRun ? "Show the result" : "Create it" },
202
+ { value: "change", label: "Change profiles" },
203
+ { value: "cancel", label: "Cancel" },
204
+ ],
205
+ initialValue: "create",
206
+ });
207
+ if (next === "create")
208
+ return answers;
209
+ if (next === "cancel")
210
+ return null;
211
+ }
212
+ }
213
+ // --- Entry point ------------------------------------------------------------------
214
+ export async function create(options, prompter) {
215
+ const all = loadProfiles();
216
+ if (prompter) {
217
+ const answers = await wizard(options, prompter, all);
218
+ if (!answers) {
219
+ prompter.outro("Cancelled — nothing was created.");
220
+ return 1;
221
+ }
222
+ const spin = prompter.spinner();
223
+ spin.start(options.dryRun ? "Checking" : "Creating your project");
224
+ const result = generate(answers, options.dryRun);
225
+ if (!result.ok) {
226
+ spin.stop("Nothing was created.");
227
+ for (const error of result.errors ?? [])
228
+ prompter.error(error);
229
+ return 1;
230
+ }
231
+ if (options.dryRun) {
232
+ spin.stop("Dry run complete — nothing was written.");
233
+ prompter.outro(`${display(answers.destination)} would be created with ${result.files} files.`);
234
+ return 0;
235
+ }
236
+ spin.stop("Project created.");
237
+ const done = finish(answers, result, all);
238
+ prompter.note(done.text, "Groundwork");
239
+ prompter.outro(done.ok ? "Your project is ready." : "Created, but the documentation check found problems.");
240
+ return done.ok ? 0 : 1;
241
+ }
242
+ // Non-interactive: everything must be given explicitly.
243
+ if (!options.dir && !options.name) {
244
+ throw new GroundworkError("Give a project folder, for example: create-groundwork my-project --profiles web", 2);
245
+ }
246
+ if (options.profiles === undefined) {
247
+ throw new GroundworkError("Choose profiles with --profiles (for example --profiles application,backend-api, or --profiles none for core only).\n" +
248
+ "Run `groundwork profiles` to see them, or run without --yes in a terminal for guided selection.", 2);
249
+ }
250
+ const name = options.name ?? options.dir.split(/[\\/]/).filter(Boolean).at(-1);
251
+ const answers = {
252
+ name,
253
+ description: options.description ?? "",
254
+ destination: resolve(options.dir ?? slug(name)),
255
+ profiles: options.profiles.filter((id) => id !== "none"),
256
+ };
257
+ const result = generate(answers, options.dryRun);
258
+ if (!result.ok) {
259
+ for (const error of result.errors ?? [])
260
+ console.error(`${red("Error:")} ${error}`);
261
+ console.error("Nothing was created.");
262
+ return 1;
263
+ }
264
+ if (options.dryRun) {
265
+ console.log(`${bold("Dry run")} — nothing was written.\n`);
266
+ console.log(reviewText(answers, result, all));
267
+ return 0;
268
+ }
269
+ const done = finish(answers, result, all);
270
+ console.log(`${bold(`Groundwork ${VERSION}`)}\n`);
271
+ console.log(done.text);
272
+ console.log(`\n${done.ok ? "Your project is ready." : "Created, but the documentation check found problems."}`);
273
+ return done.ok ? 0 : 1;
274
+ }
package/dist/text.js ADDED
@@ -0,0 +1,31 @@
1
+ // Plain-text formatting for non-interactive output.
2
+ const useColor = process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
3
+ function style(code, reset) {
4
+ return (text) => (useColor ? `\x1b[${code}m${text}\x1b[${reset}m` : text);
5
+ }
6
+ export const bold = style(1, 22);
7
+ export const dim = style(2, 22);
8
+ export const green = style(32, 39);
9
+ export const red = style(31, 39);
10
+ /** Word-wrap `text` to `width` columns, indenting every line. */
11
+ export function wrap(text, indent = "", width = 88) {
12
+ const lines = [];
13
+ let line = "";
14
+ for (const word of text.split(/\s+/).filter(Boolean)) {
15
+ if (line && indent.length + line.length + 1 + word.length > width) {
16
+ lines.push(indent + line);
17
+ line = word;
18
+ }
19
+ else {
20
+ line = line ? `${line} ${word}` : word;
21
+ }
22
+ }
23
+ if (line)
24
+ lines.push(indent + line);
25
+ return lines.join("\n");
26
+ }
27
+ /** A bulleted item whose continuation lines align under the text. */
28
+ export function bullet(text, indent = " ", mark = "-") {
29
+ const first = `${indent}${mark} `;
30
+ return wrap(text, " ".repeat(first.length)).replace(" ".repeat(first.length), first);
31
+ }
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "create-groundwork",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "3.1.0",
4
+ "description": "Start a software project with the minimum sufficient engineering documentation, adapted to what you're building through composable profiles.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/mich-nduka/groundwork.git"
8
+ },
9
+ "homepage": "https://github.com/mich-nduka/groundwork#readme",
10
+ "bugs": {
11
+ "url": "https://github.com/mich-nduka/groundwork/issues"
12
+ },
13
+ "type": "module",
14
+ "bin": {
15
+ "create-groundwork": "dist/create.js",
16
+ "groundwork": "dist/groundwork.js"
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "template",
21
+ "CHANGELOG.md",
22
+ "MIGRATION.md"
23
+ ],
24
+ "engines": {
25
+ "node": ">=22"
26
+ },
27
+ "scripts": {
28
+ "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/create.js dist/groundwork.js",
29
+ "typecheck": "tsc -p tsconfig.json --noEmit",
30
+ "test": "bun run build && bun test",
31
+ "prepack": "bun run build && node scripts/pack-assets.mjs add",
32
+ "postpack": "node scripts/pack-assets.mjs remove"
33
+ },
34
+ "keywords": [
35
+ "scaffold",
36
+ "create",
37
+ "documentation",
38
+ "requirements",
39
+ "architecture",
40
+ "ai-agents"
41
+ ],
42
+ "license": "MIT",
43
+ "dependencies": {
44
+ "@clack/prompts": "^1.9.0"
45
+ },
46
+ "devDependencies": {
47
+ "@types/node": "^22.10.0",
48
+ "typescript": "^5.9.3"
49
+ }
50
+ }
@@ -0,0 +1,14 @@
1
+ # Repository Automation (Optional)
2
+
3
+ For GitHub users. Two starter files are included:
4
+
5
+ - `pull_request_template.md`: the pull request form. Its checkbox list mirrors the Definition of done in `AGENTS.md`, which holds the full definitions.
6
+ - `workflows/docs-check.yml`: a small CI workflow that runs `python3 scripts/check_docs.py --strict` on pushes and pull requests. The warnings come in two groups: hygiene (invalid status values, unserved capabilities, documents from inactive profiles, profile checks missing from the tooling table) and coverage (a requirement no design doc, plan or test references). Each group fails only under its flag:
7
+
8
+ - Default: only errors fail.
9
+ - `--strict`: hygiene warnings fail too.
10
+ - `--strict-coverage`: coverage warnings fail too.
11
+
12
+ `--strict-coverage` does not include `--strict`. Use both flags together to fail on everything, for example `python3 scripts/check_docs.py --strict --strict-coverage` once every requirement is referenced somewhere.
13
+
14
+ Add more workflows only when the project needs them, and make the required checks match the code standards in `AGENTS.md` (including the rows your profiles added to its tooling table) and the test strategy. Delete anything you don't use.
@@ -0,0 +1,22 @@
1
+ <!-- Pull request template. The checkbox list mirrors the Definition of done in AGENTS.md, which holds the full definitions. -->
2
+
3
+ ## Summary
4
+
5
+ What changed, and why.
6
+
7
+ ## Related requirements
8
+
9
+ Requirement IDs this change serves (for example `AUTH-FR-001`), and the `CAP-` capabilities behind them.
10
+
11
+ ## Definition of done
12
+
13
+ The full definitions live in `AGENTS.md`. Mark anything that doesn't apply with a reason.
14
+
15
+ - [ ] It meets the requirements and acceptance criteria it links to.
16
+ - [ ] Domain rules and invariants (rules that must always hold) still hold.
17
+ - [ ] Tests cover the expected behaviour and the important failure cases, and the required checks pass.
18
+ - [ ] Security, privacy, accessibility and performance impacts are considered.
19
+ - [ ] Interfaces and data migrations stay compatible, or there's a migration plan.
20
+ - [ ] Logs and metrics are useful and expose no sensitive data.
21
+ - [ ] Deployment, rollback and operational effects are understood.
22
+ - [ ] Documentation and ADRs are updated where needed.
@@ -0,0 +1,23 @@
1
+ name: Docs check
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ docs:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ # --strict fails on errors and hygiene warnings (invalid status
16
+ # values, unserved capabilities, documents from inactive profiles,
17
+ # profile checks missing from AGENTS.md). It does not fail on coverage
18
+ # warnings (unreferenced requirements). --strict-coverage does not
19
+ # include --strict: once every requirement is referenced somewhere,
20
+ # ADD the flag so coverage warnings also fail:
21
+ # python3 scripts/check_docs.py --strict --strict-coverage
22
+ - uses: actions/checkout@v4
23
+ - run: python3 scripts/check_docs.py --strict