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
@@ -0,0 +1,716 @@
1
+ #!/usr/bin/env python3
2
+ """Set up and grow a Groundwork project's documents from its profiles.
3
+
4
+ Commands:
5
+ list show every profile: purpose, when to use it, its
6
+ documents and its checks.
7
+ init PROFILE... choose the active profiles (or `init none` for core
8
+ only). Records them in PROJECT.md, creates every
9
+ required document that is missing from its template,
10
+ adds the profiles' checks to the tooling table in
11
+ AGENTS.md, and lists new files in
12
+ scaffold-manifest.json. Run it again with a new list
13
+ to add a profile later.
14
+ add PATH create one optional document from its template, for
15
+ example `add docs/ai-systems/RETRIEVAL.md`.
16
+ new DEST create a new project in DEST from this copy of
17
+ Groundwork: copies the files in scaffold-manifest.json,
18
+ fills in the project name, description and date, writes
19
+ .groundwork/config.json, then runs `init` there. Use
20
+ --profiles to choose profiles (default: none).
21
+ config show this project's Groundwork configuration: name,
22
+ profiles, version, and which recorded files changed.
23
+
24
+ Choosing profiles is a judgement call; see profiles/README.md. This script
25
+ only does the mechanical part. It never overwrites or deletes a file:
26
+ documents that already exist are kept as they are, and documents of a
27
+ profile you drop stay until you delete them (check_docs.py warns about
28
+ them). `new` builds the project in a temporary folder next to DEST and
29
+ moves it into place only when every step succeeded.
30
+
31
+ Add --dry-run to see what would change without writing anything, and
32
+ --json for machine-readable output (one JSON object; exit 1 on errors).
33
+ The `groundwork` command-line tool uses that output.
34
+
35
+ Profile order never matters: profiles are always recorded and applied in
36
+ sorted order.
37
+
38
+ Python 3.9+ standard library only. The rules come from check_docs.py, so
39
+ the two scripts always agree.
40
+ """
41
+
42
+ from __future__ import annotations
43
+
44
+ import argparse
45
+ import datetime
46
+ import hashlib
47
+ import json
48
+ import os
49
+ import re
50
+ import shutil
51
+ import subprocess
52
+ import sys
53
+ import textwrap
54
+ from pathlib import Path
55
+
56
+ sys.dont_write_bytecode = True
57
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
58
+ import check_docs as docs # noqa: E402 (needs the path set above)
59
+
60
+ ROOT = docs.ROOT
61
+ CORE = docs.CORE
62
+ CONFIG_DIR = ".groundwork"
63
+ CONFIG_FILE = f"{CONFIG_DIR}/config.json"
64
+ CONFIG_SCHEMA = 1
65
+ NAME_BULLET = re.compile(r"^\s*-\s*Name:\s*(.*?)\s*$")
66
+
67
+
68
+ class Failure(Exception):
69
+ """A problem that stops a command; the message is shown to the user."""
70
+
71
+
72
+ # --- Output -----------------------------------------------------------------
73
+
74
+
75
+ def wrap(text: str, indent: str) -> str:
76
+ return textwrap.fill(text, width=88, initial_indent=indent, subsequent_indent=indent + " ")
77
+
78
+
79
+ def emit_json(data: dict) -> int:
80
+ print(json.dumps(data, indent=2, ensure_ascii=False))
81
+ return 0 if data.get("ok") else 1
82
+
83
+
84
+ def fail(errors: list[str], as_json: bool, hint: str = "") -> int:
85
+ if as_json:
86
+ return emit_json({"ok": False, "errors": errors})
87
+ for error in errors:
88
+ print(f"FAIL: {error}")
89
+ if hint:
90
+ print(hint)
91
+ return 1
92
+
93
+
94
+ # --- Loading ----------------------------------------------------------------
95
+
96
+
97
+ def load() -> tuple[dict[str, dict], dict[str, str], list[str]]:
98
+ """Valid profiles, document owners, and any problems with them."""
99
+ if not docs.PROFILES_DIR.is_dir():
100
+ return {}, {}, ["profiles/: missing — this project has no Groundwork profiles to work from"]
101
+ profiles, problems = docs.load_profiles()
102
+ owners, ownership_problems = docs.document_owners(profiles)
103
+ return profiles, owners, problems + ownership_problems
104
+
105
+
106
+ def normalise(requested: list[str]) -> list[str]:
107
+ """`none` means no profiles; otherwise the IDs as given."""
108
+ return [] if [p.lower() for p in requested] == ["none"] else list(requested)
109
+
110
+
111
+ def template_version(root: Path = ROOT) -> str:
112
+ try:
113
+ return str(json.loads((root / "scaffold-manifest.json").read_text(encoding="utf-8"))["version"])
114
+ except (OSError, ValueError, KeyError):
115
+ return "unknown"
116
+
117
+
118
+ # --- Managed-file records (.groundwork/config.json) -------------------------
119
+ # The config records which files Groundwork generated and their SHA-256 at
120
+ # that moment. A recorded file whose content still matches is
121
+ # framework-managed; one that differs was changed by the project; a file
122
+ # that isn't recorded belongs to the project. A future `update` can use this
123
+ # to avoid overwriting anyone's edits. Active profiles live in PROJECT.md,
124
+ # not here, so there is one source of truth for them.
125
+
126
+
127
+ def digest(path: Path) -> str:
128
+ return hashlib.sha256(path.read_bytes()).hexdigest()
129
+
130
+
131
+ def read_config(root: Path = ROOT) -> dict | None:
132
+ path = root / CONFIG_FILE
133
+ if not path.is_file():
134
+ return None
135
+ try:
136
+ data = json.loads(path.read_text(encoding="utf-8"))
137
+ except (OSError, ValueError) as error:
138
+ raise Failure(f"{CONFIG_FILE}: not valid JSON ({error})") from error
139
+ if not isinstance(data, dict) or data.get("schema") != CONFIG_SCHEMA or not isinstance(data.get("files"), dict):
140
+ raise Failure(f"{CONFIG_FILE}: not a schema {CONFIG_SCHEMA} Groundwork config")
141
+ return data
142
+
143
+
144
+ def write_config(config: dict, root: Path = ROOT) -> None:
145
+ path = root / CONFIG_FILE
146
+ path.parent.mkdir(parents=True, exist_ok=True)
147
+ config["files"] = dict(sorted(config["files"].items()))
148
+ path.write_text(json.dumps(config, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
149
+
150
+
151
+ def file_status(path: str, config: dict | None, root: Path = ROOT) -> str:
152
+ """managed (unchanged since generated), modified, user (not recorded) or missing."""
153
+ target = root / path
154
+ if not target.exists():
155
+ return "missing"
156
+ recorded = (config or {}).get("files", {}).get(path)
157
+ if recorded is None:
158
+ return "user"
159
+ return "managed" if digest(target) == recorded else "modified"
160
+
161
+
162
+ def pristine(paths: list[str], config: dict | None) -> set[str]:
163
+ """Paths still exactly as Groundwork generated them."""
164
+ return {path for path in paths if file_status(path, config) == "managed"}
165
+
166
+
167
+ def record(config: dict | None, created: list[str], edited: list[str], was_pristine: set[str]) -> None:
168
+ """Record new files, and refresh edited files nobody else had changed."""
169
+ if config is None:
170
+ return
171
+ for path in created + [p for p in edited if p in was_pristine]:
172
+ if (ROOT / path).is_file():
173
+ config["files"][path] = digest(ROOT / path)
174
+ write_config(config)
175
+
176
+
177
+ # --- Small file edits shared by init and add --------------------------------
178
+
179
+
180
+ def update_manifest(new_files: list[str], dry_run: bool) -> list[str]:
181
+ """List new template-area files in scaffold-manifest.json; returns them."""
182
+ manifest = json.loads(docs.MANIFEST.read_text(encoding="utf-8"))
183
+ files = manifest["files"]
184
+ added = [path for path in new_files if path not in files and not docs.is_user_owned(Path(path))]
185
+ if added and not dry_run:
186
+ manifest["files"] = sorted(files + added)
187
+ manifest["file_count"] = len(manifest["files"])
188
+ docs.MANIFEST.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
189
+ return added
190
+
191
+
192
+ def project_lines(selected: list[str]) -> list[str]:
193
+ """PROJECT.md with the `- Profiles:` line set, adding a section if needed."""
194
+ value = ", ".join(selected) or "none"
195
+ lines = docs.read_text(docs.PROJECT).splitlines()
196
+ for index, line in enumerate(lines):
197
+ if docs.PROFILES_BULLET.match(line):
198
+ lines[index] = f"- Profiles: {value}"
199
+ return lines
200
+ section = ["## Profiles", f"- Profiles: {value}", "- Why:", ""]
201
+ at = next((i for i, line in enumerate(lines) if line.strip() == "## Links"), len(lines))
202
+ if at == len(lines) and lines and lines[-1].strip():
203
+ section.insert(0, "")
204
+ lines[at:at] = section
205
+ return lines
206
+
207
+
208
+ def tooling_lines(missing: list[tuple[str, dict]]) -> tuple[list[str], list[str]] | None:
209
+ """(AGENTS.md lines with rows appended, the rows), or None without a tooling table."""
210
+ lines = docs.read_text(docs.AGENTS).splitlines()
211
+ inside, last_row, columns = False, None, 3
212
+ for index, line in enumerate(lines):
213
+ if line.lstrip().startswith("#"):
214
+ if inside and last_row is not None:
215
+ break
216
+ inside = "tooling" in line.lower()
217
+ continue
218
+ if inside and docs.TABLE_LINE.match(line):
219
+ if last_row is None:
220
+ columns = len(line.strip().strip("|").split("|"))
221
+ last_row = index
222
+ if last_row is None:
223
+ return None
224
+ rows = [f"| {check['name']} ({profile_id} profile) |" + " |" * (columns - 1) for profile_id, check in missing]
225
+ lines[last_row + 1 : last_row + 1] = rows
226
+ return lines, rows
227
+
228
+
229
+ def write_lines(path: Path, lines: list[str]) -> None:
230
+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
231
+
232
+
233
+ # --- list -------------------------------------------------------------------
234
+
235
+
236
+ def cmd_list(profiles: dict[str, dict], as_json: bool) -> int:
237
+ order = [CORE] + sorted(p for p in profiles if p != CORE)
238
+ if as_json:
239
+ return emit_json(
240
+ {
241
+ "ok": True,
242
+ "groundworkVersion": template_version(),
243
+ "profiles": [
244
+ dict(profiles[p], readme="profiles/README.md" if p == CORE else f"profiles/{p}/README.md")
245
+ for p in order
246
+ ],
247
+ }
248
+ )
249
+ for profile_id in order:
250
+ data = profiles[profile_id]
251
+ title = f"{profile_id} — {data['name']}"
252
+ if profile_id == CORE:
253
+ title += " (always active)"
254
+ print(title)
255
+ print(wrap(data["purpose"], " "))
256
+ if profile_id != CORE:
257
+ for heading, key in (("Use when", "use_when"), ("Not when", "not_when")):
258
+ print(f" {heading}:")
259
+ for item in data[key]:
260
+ print(wrap(f"- {item}", " "))
261
+ requires = [
262
+ entry if isinstance(entry, str) else "one of " + ", ".join(entry) for entry in data["requires"]
263
+ ]
264
+ if requires:
265
+ print(f" Requires: {'; '.join(requires)}")
266
+ if data["incompatible_with"]:
267
+ print(f" Incompatible with: {', '.join(data['incompatible_with'])}")
268
+ required = [doc["path"] for doc in data["documents"] if doc["required"]]
269
+ optional = [doc for doc in data["documents"] if not doc["required"]]
270
+ if required:
271
+ print(" Required documents:")
272
+ for path in required:
273
+ print(f" - {path}")
274
+ if optional:
275
+ print(" Optional documents (create when the condition holds):")
276
+ for doc in optional:
277
+ print(wrap(f"- {doc['path']}: {doc['when']}", " "))
278
+ if data.get("checks"):
279
+ print(" Checks:")
280
+ for check in data["checks"]:
281
+ print(wrap(f"- {check['name']}: {check['what']}", " "))
282
+ print()
283
+ print("Choose by what the system does, not by its technology: see profiles/README.md.")
284
+ return 0
285
+
286
+
287
+ # --- init -------------------------------------------------------------------
288
+
289
+
290
+ def plan_init(requested: list[str], profiles: dict[str, dict], owners: dict[str, str]) -> dict:
291
+ """Everything `init` would do, decided before anything is written."""
292
+ errors = docs.check_selection(requested, profiles)
293
+ if errors:
294
+ return {"ok": False, "errors": errors}
295
+ selected = sorted(dict.fromkeys(requested))
296
+ config = read_config()
297
+ active = docs.active_profiles(selected, profiles)
298
+ required = docs.required_documents(active, profiles)
299
+
300
+ documents = []
301
+ for path in sorted(required):
302
+ owner = owners.get(path, CORE)
303
+ template = docs.template_for(owner, path)
304
+ exists = (ROOT / path).exists()
305
+ if not exists and not template.is_file():
306
+ errors.append(
307
+ f"{path}: required by core but missing, and it has no template"
308
+ " — restore it from the Groundwork release"
309
+ )
310
+ documents.append(
311
+ {
312
+ "path": path,
313
+ "owner": owner,
314
+ "template": template.relative_to(ROOT).as_posix() if template.is_file() else None,
315
+ "requiredBy": required[path],
316
+ "exists": exists,
317
+ "status": file_status(path, config),
318
+ "action": "keep" if exists else "create",
319
+ }
320
+ )
321
+
322
+ missing = docs.missing_checks(active, profiles)
323
+ missing_names = {check["name"].lower() for _, check in missing}
324
+ checks, seen = [], set()
325
+ for profile_id in active:
326
+ for check in profiles[profile_id].get("checks", []):
327
+ if check["name"].lower() in seen:
328
+ continue
329
+ seen.add(check["name"].lower())
330
+ action = "add-row" if check["name"].lower() in missing_names else "present"
331
+ checks.append({"profile": profile_id, "name": check["name"], "what": check["what"], "action": action})
332
+ table = tooling_lines(missing)
333
+
334
+ optional, shown = [], set(required)
335
+ for profile_id in active:
336
+ if profile_id == CORE:
337
+ continue
338
+ for doc in profiles[profile_id]["documents"]:
339
+ if not doc["required"] and doc["path"] not in shown and not (ROOT / doc["path"]).exists():
340
+ shown.add(doc["path"])
341
+ optional.append({"path": doc["path"], "owner": owners.get(doc["path"], CORE), "when": doc["when"]})
342
+
343
+ created = [d["path"] for d in documents if d["action"] == "create"]
344
+ return {
345
+ "ok": not errors,
346
+ "errors": errors,
347
+ "profiles": selected,
348
+ "previous": docs.declared_profiles(),
349
+ "documents": documents,
350
+ "checks": checks,
351
+ "toolingTable": table is not None,
352
+ "toolingRows": table[1] if table else [],
353
+ "optional": optional,
354
+ "inactive": [w.split(":", 1)[0] for w in docs.check_inactive_documents(selected, active, owners)],
355
+ "manifestAdditions": [p for p in created if not docs.is_user_owned(Path(p))],
356
+ }
357
+
358
+
359
+ def apply_init(plan: dict, owners: dict[str, str]) -> None:
360
+ config = read_config()
361
+ edited = ["PROJECT.md", "AGENTS.md", "scaffold-manifest.json"]
362
+ was_pristine = pristine(edited, config)
363
+ created = [d["path"] for d in plan["documents"] if d["action"] == "create"]
364
+ for path in created:
365
+ target = ROOT / path
366
+ target.parent.mkdir(parents=True, exist_ok=True)
367
+ shutil.copyfile(docs.template_for(owners.get(path, CORE), path), target)
368
+ write_lines(docs.PROJECT, project_lines(plan["profiles"]))
369
+ to_add = [(c["profile"], c) for c in plan["checks"] if c["action"] == "add-row"]
370
+ table = tooling_lines(to_add) if to_add else None
371
+ if table:
372
+ write_lines(docs.AGENTS, table[0])
373
+ update_manifest(created, dry_run=False)
374
+ record(config, created, edited, was_pristine)
375
+
376
+
377
+ def report_init(plan: dict, dry_run: bool) -> None:
378
+ def say(done: str, would: str) -> str:
379
+ return would if dry_run else done
380
+
381
+ previous = plan["previous"]
382
+ before = "not chosen yet" if previous is None else (", ".join(previous) or "none")
383
+ created = [d["path"] for d in plan["documents"] if d["action"] == "create"]
384
+ kept = [d for d in plan["documents"] if d["action"] == "keep"]
385
+ print("Dry run — nothing written." if dry_run else "Done.")
386
+ print(f"Profiles: {', '.join(plan['profiles']) or 'none (core only)'} (before: {before})")
387
+ if created:
388
+ print(say("Created from templates:", "Would create from templates:"))
389
+ for path in created:
390
+ print(f" + {path}")
391
+ if kept:
392
+ print(f"Already present, kept as they are: {len(kept)} document(s)")
393
+ added_checks = [c for c in plan["checks"] if c["action"] == "add-row"]
394
+ if added_checks and not plan["toolingTable"]:
395
+ print("No tooling table found in AGENTS.md. Add a row for each of these checks:")
396
+ for check in added_checks:
397
+ print(wrap(f"- {check['name']} ({check['profile']}): {check['what']}", " "))
398
+ elif plan["toolingRows"]:
399
+ print(say("Added", "Would add") + " rows to the tooling table in AGENTS.md (fill in the tool):")
400
+ for row in plan["toolingRows"]:
401
+ print(f" {row}")
402
+ if plan["manifestAdditions"]:
403
+ print(say("Listed", "Would list") + f" {len(plan['manifestAdditions'])} new file(s) in scaffold-manifest.json")
404
+ if plan["optional"]:
405
+ print("Optional documents — add one when its condition holds (python3 scripts/groundwork.py add PATH):")
406
+ for doc in plan["optional"]:
407
+ print(wrap(f"- {doc['path']}: {doc['when']}", " "))
408
+ if plan["inactive"]:
409
+ print("Documents from profiles that are no longer active (kept; delete them if unused):")
410
+ for path in plan["inactive"]:
411
+ print(f" - {path}")
412
+ print("Next: write why these profiles fit under '- Why:' in PROJECT.md, read each")
413
+ print("profile's README in profiles/, then run python3 scripts/check_docs.py.")
414
+
415
+
416
+ def cmd_init(requested: list[str], profiles, owners, dry_run: bool, as_json: bool) -> int:
417
+ plan = plan_init(normalise(requested), profiles, owners)
418
+ if not plan["ok"]:
419
+ return fail(plan["errors"], as_json, "Run `python3 scripts/groundwork.py list` to see the profiles.")
420
+ if not dry_run:
421
+ apply_init(plan, owners)
422
+ if as_json:
423
+ return emit_json(dict(plan, dryRun=dry_run))
424
+ report_init(plan, dry_run)
425
+ return 0
426
+
427
+
428
+ # --- add --------------------------------------------------------------------
429
+
430
+
431
+ def cmd_add(path: str, profiles, owners, dry_run: bool, as_json: bool) -> int:
432
+ path = Path(path).as_posix()
433
+ while path.startswith("./"):
434
+ path = path[2:]
435
+ active = docs.active_profiles(docs.declared_profiles(), profiles)
436
+ listed_by = [p for p in active if any(doc["path"] == path for doc in profiles[p]["documents"])]
437
+ owner = owners.get(path)
438
+ if owner is None:
439
+ return fail([f"{path}: no profile has this document — run `python3 scripts/groundwork.py list`"], as_json)
440
+ if not listed_by:
441
+ return fail(
442
+ [
443
+ f"{path}: belongs to the {owner} profile, which PROJECT.md does not list"
444
+ f" — run `python3 scripts/groundwork.py init` with {owner} added first"
445
+ ],
446
+ as_json,
447
+ )
448
+ result = {"ok": True, "path": path, "owner": owner, "dryRun": dry_run}
449
+ if (ROOT / path).exists():
450
+ if as_json:
451
+ return emit_json(dict(result, action="keep"))
452
+ print(f"{path}: already exists — nothing to do")
453
+ return 0
454
+ template = docs.template_for(owner, path)
455
+ if not template.is_file():
456
+ return fail(
457
+ [f"{path}: core ships this document in place and has no template — restore it from the Groundwork release"],
458
+ as_json,
459
+ )
460
+ source = template.relative_to(ROOT).as_posix()
461
+ if dry_run:
462
+ added = update_manifest([path], dry_run=True)
463
+ else:
464
+ config = read_config()
465
+ was_pristine = pristine(["scaffold-manifest.json"], config)
466
+ (ROOT / path).parent.mkdir(parents=True, exist_ok=True)
467
+ shutil.copyfile(template, ROOT / path)
468
+ added = update_manifest([path], dry_run=False)
469
+ record(config, [path], ["scaffold-manifest.json"], was_pristine)
470
+ if as_json:
471
+ return emit_json(dict(result, action="create", template=source, manifestAdditions=added))
472
+ print(f"{'Would create' if dry_run else 'Created'} {path} from {source}")
473
+ if added:
474
+ print(f"{'Would list' if dry_run else 'Listed'} it in scaffold-manifest.json")
475
+ return 0
476
+
477
+
478
+ # --- new --------------------------------------------------------------------
479
+
480
+
481
+ def check_text(value: str, label: str, limit: int, required: bool) -> list[str]:
482
+ if required and not value.strip():
483
+ return [f"{label} is required"]
484
+ if "\n" in value or "\r" in value:
485
+ return [f"{label} must be one line"]
486
+ if len(value) > limit:
487
+ return [f"{label} must be at most {limit} characters"]
488
+ if "{{" in value or "}}" in value:
489
+ return [f"{label} must not contain '{{{{' or '}}}}'"]
490
+ return []
491
+
492
+
493
+ def render(text: str, values: dict[str, str]) -> str:
494
+ """Fill in {{PLACEHOLDER}}s; lines that held one lose trailing spaces."""
495
+ out = []
496
+ for line in text.split("\n"):
497
+ if "{{" in line:
498
+ for key, value in values.items():
499
+ line = line.replace("{{" + key + "}}", value)
500
+ line = line.rstrip()
501
+ out.append(line)
502
+ return "\n".join(out)
503
+
504
+
505
+ def is_inside(path: Path, parent: Path) -> bool:
506
+ try:
507
+ path.relative_to(parent)
508
+ return True
509
+ except ValueError:
510
+ return False
511
+
512
+
513
+ def packaged_name(rel: str) -> str:
514
+ """npm packages can't contain `.gitignore` files, so the npm package of
515
+ Groundwork ships `_gitignore` instead; `new` restores the real name."""
516
+ folder, _, name = rel.rpartition("/")
517
+ if not name.startswith("."):
518
+ return rel
519
+ return f"{folder}/_{name[1:]}" if folder else f"_{name[1:]}"
520
+
521
+
522
+ def copy_template(staging: Path, values: dict[str, str]) -> dict[str, str]:
523
+ """Copy every manifest file into staging; returns {path: sha256}."""
524
+ manifest = json.loads(docs.MANIFEST.read_text(encoding="utf-8"))
525
+ hashes: dict[str, str] = {}
526
+ for rel in manifest["files"]:
527
+ source, target = ROOT / rel, staging / rel
528
+ if not source.is_file():
529
+ source = ROOT / packaged_name(rel)
530
+ if not source.is_file():
531
+ raise Failure(f"{rel}: listed in this Groundwork's manifest but missing — the template is incomplete")
532
+ target.parent.mkdir(parents=True, exist_ok=True)
533
+ if rel.endswith(".md"):
534
+ target.write_text(render(source.read_text(encoding="utf-8"), values), encoding="utf-8")
535
+ else:
536
+ shutil.copyfile(source, target)
537
+ shutil.copymode(source, target)
538
+ hashes[rel] = digest(target)
539
+ return hashes
540
+
541
+
542
+ def cmd_new(dest: str, name: str, description: str, requested: list[str], dry_run: bool, as_json: bool) -> int:
543
+ profiles, owners, problems = load()
544
+ if problems:
545
+ return fail(problems, as_json)
546
+ target = Path(dest).expanduser().resolve()
547
+ name = (name or target.name).strip()
548
+ description = description.strip()
549
+ requested = normalise(requested)
550
+ selected = sorted(dict.fromkeys(requested))
551
+ errors = check_text(name, "Project name", 100, True) + check_text(description, "Description", 300, False)
552
+ errors += docs.check_selection(requested, profiles)
553
+ if target.exists() and (not target.is_dir() or any(target.iterdir())):
554
+ errors.append(f"{target}: already exists and is not empty — choose a new or empty folder")
555
+ if is_inside(target, ROOT):
556
+ errors.append(f"{target}: is inside this copy of Groundwork — choose a folder outside {ROOT}")
557
+ if not target.parent.is_dir():
558
+ errors.append(f"{target.parent}: does not exist — create it first, or choose another folder")
559
+ if errors:
560
+ return fail(errors, as_json)
561
+
562
+ staging = target.parent / f".{target.name}.groundwork-{os.getpid()}"
563
+ today = datetime.date.today().isoformat()
564
+ values = {"PROJECT_NAME": name, "PROJECT_DESCRIPTION": description, "PROJECT_DATE": today}
565
+ version = template_version()
566
+ try:
567
+ staging.mkdir()
568
+ except OSError as error:
569
+ return fail([f"{staging}: cannot create a staging folder ({error})"], as_json)
570
+ try:
571
+ hashes = copy_template(staging, values)
572
+ config = {"schema": CONFIG_SCHEMA, "groundworkVersion": version, "generatedAt": today, "files": hashes}
573
+ write_config(config, staging)
574
+ command = [sys.executable, "-I", str(staging / "scripts" / "groundwork.py"), "init"]
575
+ command += (selected or ["none"]) + ["--json"] + (["--dry-run"] if dry_run else [])
576
+ result = subprocess.run(command, capture_output=True, text=True, encoding="utf-8")
577
+ try:
578
+ plan = json.loads(result.stdout)
579
+ except ValueError:
580
+ raise Failure(f"init failed in the new project: {(result.stderr or result.stdout).strip()}") from None
581
+ if not plan.get("ok"):
582
+ raise Failure("; ".join(plan.get("errors") or ["init failed in the new project"]))
583
+ if not dry_run:
584
+ if target.exists():
585
+ target.rmdir() # checked above: an empty folder
586
+ staging.rename(target)
587
+ except (Failure, OSError) as error:
588
+ return fail([str(error)], as_json)
589
+ finally:
590
+ if staging.exists():
591
+ shutil.rmtree(staging)
592
+
593
+ summary = {
594
+ "ok": True,
595
+ "dryRun": dry_run,
596
+ "destination": str(target),
597
+ "name": name,
598
+ "description": description,
599
+ "groundworkVersion": version,
600
+ "files": len(hashes),
601
+ "init": plan,
602
+ }
603
+ if as_json:
604
+ return emit_json(summary)
605
+ print(f"{'Dry run — nothing written. Would create' if dry_run else 'Created'} {name} in {target}")
606
+ print(f"Groundwork {version} files: {len(hashes)}; profiles: {', '.join(selected) or 'none (core only)'}")
607
+ for doc in plan["documents"]:
608
+ if doc["action"] == "create":
609
+ print(f" + {doc['path']}")
610
+ if not dry_run:
611
+ print(f"Next: cd {target} and run python3 scripts/check_docs.py")
612
+ return 0
613
+
614
+
615
+ # --- config -----------------------------------------------------------------
616
+
617
+
618
+ def cmd_config(as_json: bool) -> int:
619
+ try:
620
+ config = read_config()
621
+ except Failure as error:
622
+ return fail([str(error)], as_json)
623
+ name = ""
624
+ for line in docs.read_text(docs.PROJECT).splitlines():
625
+ match = NAME_BULLET.match(line)
626
+ if match:
627
+ name = match.group(1)
628
+ break
629
+ if name.startswith(("{{", "[")):
630
+ name = ""
631
+ selected = docs.declared_profiles()
632
+ statuses: dict[str, list[str]] = {"managed": [], "modified": [], "missing": []}
633
+ for path in sorted((config or {}).get("files", {})):
634
+ statuses[file_status(path, config)].append(path)
635
+ data = {
636
+ "ok": True,
637
+ "root": str(ROOT),
638
+ "name": name,
639
+ "profiles": selected,
640
+ "templateVersion": template_version(),
641
+ "config": None
642
+ if config is None
643
+ else {
644
+ "path": CONFIG_FILE,
645
+ "groundworkVersion": config.get("groundworkVersion"),
646
+ "generatedAt": config.get("generatedAt"),
647
+ "files": statuses,
648
+ },
649
+ }
650
+ if as_json:
651
+ return emit_json(data)
652
+ print(f"Project: {name or '(no name in PROJECT.md)'}")
653
+ print(f"Folder: {ROOT}")
654
+ profile_text = "not chosen yet" if selected is None else (", ".join(selected) or "none (core only)")
655
+ print(f"Profiles: {profile_text} (from PROJECT.md)")
656
+ print(f"Groundwork version: {template_version()} (from scaffold-manifest.json)")
657
+ if config is None:
658
+ print(f"No {CONFIG_FILE}: this project predates Groundwork 3.1, so no files are recorded as managed.")
659
+ return 0
660
+ print(f"Generated: {config.get('generatedAt')} with Groundwork {config.get('groundworkVersion')}")
661
+ print(
662
+ f"Recorded files: {len(statuses['managed'])} unchanged, "
663
+ f"{len(statuses['modified'])} changed by the project, {len(statuses['missing'])} deleted"
664
+ )
665
+ for label, mark in (("modified", "~"), ("missing", "-")):
666
+ for path in statuses[label]:
667
+ print(f" {mark} {path}")
668
+ return 0
669
+
670
+
671
+ # --- main -------------------------------------------------------------------
672
+
673
+
674
+ def main() -> int:
675
+ parser = argparse.ArgumentParser(description="Set up and grow a Groundwork project's documents from its profiles.")
676
+ sub = parser.add_subparsers(dest="command", required=True)
677
+
678
+ def command(name: str, help_text: str, dry_run: bool = True) -> argparse.ArgumentParser:
679
+ sub_parser = sub.add_parser(name, help=help_text)
680
+ if dry_run:
681
+ sub_parser.add_argument("--dry-run", action="store_true", help="show what would change")
682
+ sub_parser.add_argument("--json", action="store_true", help="print one JSON object")
683
+ return sub_parser
684
+
685
+ command("list", "show every profile", dry_run=False)
686
+ init = command("init", "choose the active profiles and create their documents")
687
+ init.add_argument("profiles", nargs="+", help="profile IDs, or 'none' for core only")
688
+ add = command("add", "create an optional document from its template")
689
+ add.add_argument("path", help="document path, for example docs/ai-systems/RETRIEVAL.md")
690
+ new = command("new", "create a new project from this copy of Groundwork")
691
+ new.add_argument("dest", help="folder to create (must be new or empty)")
692
+ new.add_argument("--name", default="", help="project name (default: the folder name)")
693
+ new.add_argument("--description", default="", help="one-line description")
694
+ new.add_argument("--profiles", nargs="*", default=[], help="profile IDs (default: none)")
695
+ command("config", "show this project's Groundwork configuration", dry_run=False)
696
+ args = parser.parse_args()
697
+
698
+ if args.command == "new":
699
+ return cmd_new(args.dest, args.name, args.description, args.profiles, args.dry_run, args.json)
700
+ if args.command == "config":
701
+ return cmd_config(args.json)
702
+ profiles, owners, problems = load()
703
+ if problems:
704
+ return fail(problems, args.json)
705
+ try:
706
+ if args.command == "list":
707
+ return cmd_list(profiles, args.json)
708
+ if args.command == "init":
709
+ return cmd_init(args.profiles, profiles, owners, args.dry_run, args.json)
710
+ return cmd_add(args.path, profiles, owners, args.dry_run, args.json)
711
+ except Failure as error:
712
+ return fail([str(error)], args.json)
713
+
714
+
715
+ if __name__ == "__main__":
716
+ sys.exit(main())