@open-agent-toolkit/cli 0.3.28 → 0.3.29
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/README.md +2 -0
- package/assets/bundle-metadata.json +1 -1
- package/assets/docs/docs-tooling/add-docs-to-a-repo.md +2 -0
- package/assets/docs/docs-tooling/commands.md +47 -2
- package/assets/public-package-versions.json +4 -4
- package/assets/skills/authoring-docs/SKILL.md +2 -2
- package/assets/skills/authoring-docs/references/information-architecture.md +5 -2
- package/assets/skills/authoring-docs/references/page-templates/alert-runbook.md +63 -0
- package/assets/skills/authoring-docs/references/page-templates/command-reference.md +55 -0
- package/assets/skills/authoring-docs/references/page-templates/decisions-pointer.md +44 -0
- package/assets/skills/authoring-docs/references/page-templates/engineering-feature.md +53 -0
- package/assets/skills/authoring-docs/references/page-templates/per-area-agents.md +42 -0
- package/assets/skills/authoring-docs/references/page-templates/product-feature.md +49 -0
- package/assets/skills/authoring-docs/references/page-templates/qa-validation.md +59 -0
- package/assets/skills/authoring-docs/references/page-templates/screen-spec.md +51 -0
- package/assets/skills/authoring-docs/references/page-templates/skill-command-guide.md +44 -0
- package/assets/skills/authoring-docs/references/page-templates/solution-record.md +43 -0
- package/assets/skills/authoring-docs/references/templates.md +22 -2
- package/assets/skills/oat-docs-bootstrap/SKILL.md +11 -5
- package/dist/commands/docs/init/content.d.ts +23 -0
- package/dist/commands/docs/init/content.d.ts.map +1 -0
- package/dist/commands/docs/init/content.js +361 -0
- package/dist/commands/docs/init/index.d.ts.map +1 -1
- package/dist/commands/docs/init/index.js +32 -1
- package/dist/commands/docs/init/markdown.d.ts.map +1 -1
- package/dist/commands/docs/init/markdown.js +21 -2
- package/dist/commands/docs/init/resolve-options.d.ts +4 -1
- package/dist/commands/docs/init/resolve-options.d.ts.map +1 -1
- package/dist/commands/docs/init/resolve-options.js +4 -0
- package/dist/commands/docs/init/scaffold.d.ts.map +1 -1
- package/dist/commands/docs/init/scaffold.js +20 -1
- package/dist/release/public-package-contract.d.ts.map +1 -1
- package/dist/release/public-package-contract.js +10 -0
- package/package.json +3 -3
|
@@ -551,8 +551,8 @@ docs/
|
|
|
551
551
|
## IA Proposal
|
|
552
552
|
|
|
553
553
|
Use for bootstrap or an existing-tree `--ia` analysis. This proposes structure;
|
|
554
|
-
it neither persists an IA decision nor materializes a preset.
|
|
555
|
-
|
|
554
|
+
it neither persists an IA decision nor materializes a preset. Use the copyable
|
|
555
|
+
page assets below and the page-type guidance to
|
|
556
556
|
plan their content.
|
|
557
557
|
|
|
558
558
|
````markdown
|
|
@@ -601,3 +601,23 @@ questions. Record an explicit choice before replacement or a second app.
|
|
|
601
601
|
Existing docs default to analyze → apply of approved recommendations.
|
|
602
602
|
No private exemplar text, copied external contents or unapproved moves.}
|
|
603
603
|
````
|
|
604
|
+
|
|
605
|
+
## Copyable page assets
|
|
606
|
+
|
|
607
|
+
These Markdown bodies are the canonical source for approved preset scaffolds under
|
|
608
|
+
`contributing/templates/`. They are drafts, excluded from reader navigation and
|
|
609
|
+
manifest inventories through `documentation.nonReaderPaths`. Prefer local templates
|
|
610
|
+
when present; remove prompts and unneeded sections before publishing a reader page.
|
|
611
|
+
A Solution record captures an incident diagnosis, unlike the solution page type; a
|
|
612
|
+
Decisions pointer routes to records and never substitutes for an ADR.
|
|
613
|
+
|
|
614
|
+
- [Product feature](page-templates/product-feature.md) - Intended behavior and reader-visible boundaries for one feature or journey.
|
|
615
|
+
- [Engineering feature](page-templates/engineering-feature.md) - Implementation contracts and testing seams for one feature.
|
|
616
|
+
- [QA validation](page-templates/qa-validation.md) - Reproducible behavioral validation for one feature or journey.
|
|
617
|
+
- [Screen spec](page-templates/screen-spec.md) - Shared visible-state contract only for screens serving several journeys.
|
|
618
|
+
- [Alert runbook](page-templates/alert-runbook.md) - Triage, recovery and verification for a specific operational alert.
|
|
619
|
+
- [Solution record](page-templates/solution-record.md) - An incident diagnosis and fix, distinct from a capability solution guide.
|
|
620
|
+
- [Command reference](page-templates/command-reference.md) - Verified command inputs, outputs and mutation boundaries.
|
|
621
|
+
- [Skill or command guide](page-templates/skill-command-guide.md) - A reader task guide for invoking one skill or command.
|
|
622
|
+
- [Decisions pointer](page-templates/decisions-pointer.md) - A curated guide to consequential decisions, not a ledger or an ADR.
|
|
623
|
+
- [Per-area AGENTS](page-templates/per-area-agents.md) - Local authoring instructions excluded from reader navigation.
|
|
@@ -6,7 +6,7 @@ disable-model-invocation: true
|
|
|
6
6
|
user-invocable: true
|
|
7
7
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
8
8
|
metadata:
|
|
9
|
-
version: '1.4.
|
|
9
|
+
version: '1.4.5'
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
# Docs Bootstrap
|
|
@@ -120,8 +120,8 @@ The detailed framework procedures below apply to Fumadocs/MkDocs. When the selec
|
|
|
120
120
|
2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
|
|
121
121
|
Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
|
|
122
122
|
|
|
123
|
-
3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
|
|
124
|
-
4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions.
|
|
123
|
+
3. **Invoke CLI:** For fresh setup, pass the explicitly approved nearest preset and anticipated reader-page count together as `--ia-preset <preset> --planned-pages <count>` only when both are advertised. Adoption never receives these flags. Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without template repairs. For success, read config back to resolve the actual content root and authored index.
|
|
124
|
+
4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Without preset inputs, fresh setup creates only authored `index.md` and `contributing.md` in the target. For approved preset runs, compare the actual reader tree with the accepted selection: selected track directories at 15 or more anticipated reader pages, grouped root Contents and flat reader pages below 15, and flat structure for `flat-small` at any count. Inspect purpose, entry principle, useful section guidance and Contents links to actual pages. Verify the applicable `contributing/templates/` subset (all ten for triad, Engineering feature plus the six operations/reference/agent shapes for domain, six for other presets), retained when flat; `documentation.nonReaderPaths` includes `contributing/templates/**` without losing prior settings, and templates stay outside reader Contents and any separately configured manifest. Check the track table and accepted-selection guidance in `contributing.md`, separate from later IA persistence. In every Markdown run, verify no docs-root AGENTS, app package, framework config, dependencies, sidebar, site build, default manifest, or root build changes. Run `$CLI_CMD docs check --target-dir <literal-root>` and already documented lint/link/format checks when applicable. Errors block conformance; warnings remain review items. Use `references/pr-ci.md` to present checker-only PR wiring with empty build/manifest inputs unless a generated external manifest was separately configured; apply only the approved workflow diff. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
|
|
125
125
|
5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
|
|
126
126
|
6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
|
|
127
127
|
7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
|
|
@@ -392,7 +392,7 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
|
|
|
392
392
|
`ask_user` with local/external source citations. Non-repo guidance stays read-only
|
|
393
393
|
and private exemplars are never copied. Cite ordered sources in the proposal
|
|
394
394
|
and final summary, including the built-in path when it wins.
|
|
395
|
-
6. Obtain explicit approval of the selected IA before persistence. After setup,
|
|
395
|
+
6. Include the anticipated total reader-page count in the proposal (exclude contributor, template and toolchain pages). Obtain explicit approval of the selected IA and count before fresh preset materialization or persistence. For a fresh empty target, transport the approved nearest preset and count using the capability-gated flags below. Existing surfaces and explicit adoption retain their preserve-and-analyze flow without preset flags. After setup,
|
|
396
396
|
use apply's `record-ia` procedure: target-repo `oat pjm doctor --json` and
|
|
397
397
|
adoption check before `oat decision new`, an Information architecture section
|
|
398
398
|
in the framework docs-app AGENTS.md or Markdown contributing page, and shared
|
|
@@ -401,7 +401,7 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
|
|
|
401
401
|
it unrecorded. Do not silently initialize PJM. For an existing surface, hand
|
|
402
402
|
off an analysis artifact plus approved recommendation IDs to apply, with
|
|
403
403
|
individual approval for explicit record/restructure/tooling items.
|
|
404
|
-
|
|
404
|
+
Preset materialization is CLI-owned and only for fresh empty targets; it does not record an IA decision or change ownership for an existing app.
|
|
405
405
|
Sidebar ownership is separately chosen for existing framework apps; absent
|
|
406
406
|
remains undeclared, Markdown ignores it, and no automatic nav generation is
|
|
407
407
|
authorized by IA approval alone.
|
|
@@ -436,6 +436,7 @@ Base flags (always passed):
|
|
|
436
436
|
|
|
437
437
|
Capability-gated flags (added only when the Capability Probe reports support):
|
|
438
438
|
|
|
439
|
+
- `--ia-preset {preset}` and `--planned-pages {count}` — pass together only for an explicitly approved fresh empty target, after both capabilities are advertised. IDs: `product-engineering-qa`, `consumer-maintainer`, `domain-engineering`, `task-type`, `toolkit-cli`, `flat-small`. Count is an integer of at least 1, with no implicit preset/default or interactive CLI choice. If either capability is absent, stop this handoff and recommend a CLI update. Do not substitute a file-write plan, copy templates manually, or use preset init to replace an existing surface.
|
|
439
440
|
- `--site-name {siteName}` — only if `capabilities.siteNameFlag === true`. If absent, stop before scaffolding and recommend updating the CLI; do not rewrite the older template output.
|
|
440
441
|
- `--no-root-patch` — only if `capabilities.noRootPatchFlag === true` and the Preflight / Conflict Resolution result says root package mutation should be skipped. This is recommended for no-root-package repositories or when the user explicitly chose no root mutation; current CLI builds also auto-skip when no root `package.json` exists, so the flag is optional documentation of intent, not a recovery mechanism.
|
|
441
442
|
|
|
@@ -445,12 +446,17 @@ Do not pass flags the CLI doesn't advertise. Never assume a flag exists because
|
|
|
445
446
|
|
|
446
447
|
Before CLI invocation, run `$CLI_CMD docs init --help` once. Record:
|
|
447
448
|
|
|
449
|
+
- `iaPresetFlag` and `plannedPagesFlag`: whether `--ia-preset` and `--planned-pages` are both advertised. Require both for the approved fresh selection, including the Markdown path.
|
|
448
450
|
- `siteNameFlag`: whether `--site-name` is advertised.
|
|
449
451
|
- `agentsMdScaffold`: whether the installed framework template file list confirms native app-root `AGENTS.md` scaffolding; if unavailable, record unknown and verify actual output after invocation. Do not infer a CLI flag from this capability.
|
|
450
452
|
- `noRootPatchFlag`: whether `--no-root-patch` is advertised.
|
|
451
453
|
|
|
452
454
|
If the probe fails or returns no help, stop with the verbatim error and recommend updating or repairing the CLI. Never guess capabilities.
|
|
453
455
|
|
|
456
|
+
After preset init, inspect actual files and config before claiming success. At 15 or more anticipated reader pages, verify the selected track directories: triad `product/`, `engineering/`, `qa/`; consumer/maintainer `consumer/`, `maintainer/`; domain `engineering/`; task type `tutorials/`, `how-to/`, `reference/`, `explanation/`; toolkit `tools/`, `workflows/`. Below 15, or for `flat-small` at any count, verify grouped root Contents and flat reader pages instead. The exact CLI cutoff implements the approximate authoring heuristic, without selecting a different reader model. Track indexes own purpose, entry principle and useful section headings; they do not manufacture every section directory.
|
|
457
|
+
|
|
458
|
+
Verify the track table/accepted-selection guidance in framework app-root AGENTS, or Markdown `contributing.md`. Engineering stays hybrid (domain/implementation contracts alongside paired features); Product/QA enter by feature or journey. Check the applicable `contributing/templates/` subset: all ten for triad, Engineering feature plus the six operations/reference/agent shapes for domain, six for other presets. Size collapse retains the subset. Screen specs and per-area AGENTS are copyable only, never automatically instantiated. Verify `documentation.nonReaderPaths` includes `contributing/templates/**` without losing prior settings, and templates stay out of Contents, sidebar and manifest. `excludes` remains manifest-only; pinned MkDocs may still render non-reader routes and retains `use_directory_urls: false`. Run the real checker and framework nav `--check`; repair failures without suppressing rules. Keep approved-selection evidence separate from the later `record-ia` persistence/adoption result.
|
|
459
|
+
|
|
454
460
|
After scaffolding, inspect `<appRoot>/AGENTS.md`: absence is a missing-capability finding with analyze/manual upgrade advice; any existing file is preserved. No missing-file bridge is permitted. Check template output against the current scaffold contract. Older output with missing metadata, unresolved Node-version advice, missing generated-files guidance, extension-less Contents links, duplicated agent instructions, or a Fumadocs wrapper that loses static export settings becomes a finding under `oat-docs-analyze`'s legacy scaffold checks (load that skill from installed scope and resolve `references/legacy-scaffold-checks.md` from its own directory). Record the observed path and evidence, then offer analyze; do not reinstate template patches. Ambiguous or user-authored shapes are reported for review, never overwritten.
|
|
455
461
|
|
|
456
462
|
**3c. Invoke the CLI.**
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export declare const IA_PRESETS: readonly ['product-engineering-qa', 'consumer-maintainer', 'domain-engineering', 'task-type', 'toolkit-cli', 'flat-small'];
|
|
2
|
+
export type IaPreset = (typeof IA_PRESETS)[number];
|
|
3
|
+
export interface PresetSelection {
|
|
4
|
+
iaPreset?: IaPreset;
|
|
5
|
+
plannedPages?: number;
|
|
6
|
+
}
|
|
7
|
+
/** Validate the opt-in pair before planning or writing any scaffold files. */
|
|
8
|
+
export declare function resolvePresetSelection(preset?: string, count?: string | number): PresetSelection;
|
|
9
|
+
export declare function mergeTemplateExclusion(paths?: string[]): string[];
|
|
10
|
+
/** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
|
|
11
|
+
export declare function planPresetContent(options: PresetSelection & {
|
|
12
|
+
assetsRoot: string;
|
|
13
|
+
siteName: string;
|
|
14
|
+
siteDescription?: string;
|
|
15
|
+
markdown: boolean;
|
|
16
|
+
}): Promise<{
|
|
17
|
+
files: {
|
|
18
|
+
name: string;
|
|
19
|
+
content: string;
|
|
20
|
+
}[];
|
|
21
|
+
guidance: string;
|
|
22
|
+
} | null>;
|
|
23
|
+
//# sourceMappingURL=content.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/content.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,YACrB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,YAAY,CACJ,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GACtB,eAAe,CAiBjB;AAmSD,wBAAgB,sBAAsB,CAAC,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAErE;AAQD,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,eAAe,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB,GACA,OAAO,CAAC;IACT,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAAC,CAwFR"}
|
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
export const IA_PRESETS = [
|
|
4
|
+
'product-engineering-qa',
|
|
5
|
+
'consumer-maintainer',
|
|
6
|
+
'domain-engineering',
|
|
7
|
+
'task-type',
|
|
8
|
+
'toolkit-cli',
|
|
9
|
+
'flat-small',
|
|
10
|
+
];
|
|
11
|
+
/** Validate the opt-in pair before planning or writing any scaffold files. */
|
|
12
|
+
export function resolvePresetSelection(preset, count) {
|
|
13
|
+
if (preset === undefined && count === undefined)
|
|
14
|
+
return {};
|
|
15
|
+
if (preset === undefined || count === undefined)
|
|
16
|
+
throw new Error('--ia-preset and --planned-pages are required together.');
|
|
17
|
+
if (!IA_PRESETS.includes(preset))
|
|
18
|
+
throw new Error(`Unknown IA preset "${preset}". Choose: ${IA_PRESETS.join(', ')}.`);
|
|
19
|
+
if (!/^\d+$/.test(String(count)) ||
|
|
20
|
+
!Number.isSafeInteger(Number(count)) ||
|
|
21
|
+
Number(count) < 1)
|
|
22
|
+
throw new Error('--planned-pages must be an integer of at least 1 (anticipated reader pages only).');
|
|
23
|
+
return { iaPreset: preset, plannedPages: Number(count) };
|
|
24
|
+
}
|
|
25
|
+
const engineering = {
|
|
26
|
+
path: 'engineering',
|
|
27
|
+
title: 'Engineering',
|
|
28
|
+
principle: 'Domain and implementation contracts alongside paired feature pages',
|
|
29
|
+
purpose: 'Engineering is hybrid: enter by domain or implementation contract when changing shared behavior, and by feature when following its paired Product and QA pages.',
|
|
30
|
+
sections: [
|
|
31
|
+
[
|
|
32
|
+
'Domain contracts',
|
|
33
|
+
'Place shared domain rules, interface boundaries and invariants here; link the features that depend on them.',
|
|
34
|
+
],
|
|
35
|
+
[
|
|
36
|
+
'Feature implementation',
|
|
37
|
+
'Link implementation details for each feature to its Product intent, shared domain contracts and QA validation.',
|
|
38
|
+
],
|
|
39
|
+
[
|
|
40
|
+
'Operations and failure modes',
|
|
41
|
+
'Place diagnosis, recovery and operational limits here; link runbooks and incident solution records.',
|
|
42
|
+
],
|
|
43
|
+
],
|
|
44
|
+
};
|
|
45
|
+
const TRACKS = {
|
|
46
|
+
'product-engineering-qa': [
|
|
47
|
+
{
|
|
48
|
+
path: 'product',
|
|
49
|
+
title: 'Product',
|
|
50
|
+
principle: 'Feature or journey',
|
|
51
|
+
purpose: 'Product readers enter by feature or journey to understand availability, intended behavior and user-visible boundaries.',
|
|
52
|
+
sections: [
|
|
53
|
+
[
|
|
54
|
+
'Availability',
|
|
55
|
+
'Describe who can use each feature, supported environments and known availability limits; link its feature page.',
|
|
56
|
+
],
|
|
57
|
+
[
|
|
58
|
+
'Journeys and behavior',
|
|
59
|
+
'Place feature goals and ordered user journeys here, with their expected user-visible outcomes.',
|
|
60
|
+
],
|
|
61
|
+
[
|
|
62
|
+
'States and boundaries',
|
|
63
|
+
'Document visible states, transitions, empty and error behavior, and what each feature excludes.',
|
|
64
|
+
],
|
|
65
|
+
],
|
|
66
|
+
},
|
|
67
|
+
engineering,
|
|
68
|
+
{
|
|
69
|
+
path: 'qa',
|
|
70
|
+
title: 'QA',
|
|
71
|
+
principle: 'Feature or journey with reproducible verification',
|
|
72
|
+
purpose: 'QA readers enter by feature or journey to reproduce behavior with named seeds, ready signals, exact expectations and cleanup.',
|
|
73
|
+
sections: [
|
|
74
|
+
[
|
|
75
|
+
'Seeds and configuration',
|
|
76
|
+
'Place reproducible test data, configuration and ready signals here; identify safe setup and cleanup.',
|
|
77
|
+
],
|
|
78
|
+
[
|
|
79
|
+
'Scenarios',
|
|
80
|
+
'Organize validation by feature or journey, with actions, exact expectations and links to the supported contract.',
|
|
81
|
+
],
|
|
82
|
+
[
|
|
83
|
+
'Execution evidence',
|
|
84
|
+
'Keep dated runs, observed results and discrepancies here, separate from planned automation and implemented assertions.',
|
|
85
|
+
],
|
|
86
|
+
],
|
|
87
|
+
},
|
|
88
|
+
],
|
|
89
|
+
'consumer-maintainer': [
|
|
90
|
+
{
|
|
91
|
+
path: 'consumer',
|
|
92
|
+
title: 'Consumer',
|
|
93
|
+
principle: 'Reader task and supported contract',
|
|
94
|
+
purpose: 'Consumers enter by the task they need to complete and the supported contract they can rely on.',
|
|
95
|
+
sections: [
|
|
96
|
+
[
|
|
97
|
+
'Start here',
|
|
98
|
+
'Link the shortest supported first task, including prerequisites and a result the reader can verify.',
|
|
99
|
+
],
|
|
100
|
+
[
|
|
101
|
+
'Tasks',
|
|
102
|
+
'Place bounded procedures for consumer goals here; link required inputs and verification steps.',
|
|
103
|
+
],
|
|
104
|
+
[
|
|
105
|
+
'Supported reference',
|
|
106
|
+
'Collect supported interfaces, inputs, outputs and compatibility limits for consumer lookup.',
|
|
107
|
+
],
|
|
108
|
+
],
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
path: 'maintainer',
|
|
112
|
+
title: 'Maintainer',
|
|
113
|
+
principle: 'Change, operation and maintenance responsibility',
|
|
114
|
+
purpose: 'Maintainers enter by the responsibility they own: implementation, delivery, operations or support of the shared contract.',
|
|
115
|
+
sections: [
|
|
116
|
+
[
|
|
117
|
+
'Implementation contracts',
|
|
118
|
+
'Place internal interfaces, invariants and ownership boundaries here for maintainers changing behavior.',
|
|
119
|
+
],
|
|
120
|
+
[
|
|
121
|
+
'Delivery',
|
|
122
|
+
'Document release preparation, compatibility checks, rollout and rollback responsibilities here.',
|
|
123
|
+
],
|
|
124
|
+
[
|
|
125
|
+
'Operations',
|
|
126
|
+
'Link routine maintenance, diagnostic procedures and recovery runbooks, with their authority and safety boundaries.',
|
|
127
|
+
],
|
|
128
|
+
],
|
|
129
|
+
},
|
|
130
|
+
],
|
|
131
|
+
'domain-engineering': [engineering],
|
|
132
|
+
'task-type': [
|
|
133
|
+
{
|
|
134
|
+
path: 'tutorials',
|
|
135
|
+
title: 'Tutorials',
|
|
136
|
+
principle: 'Learning by a complete safe exercise',
|
|
137
|
+
purpose: 'Learners enter through a guided exercise with a clear starting state and an independently verifiable result.',
|
|
138
|
+
sections: [
|
|
139
|
+
[
|
|
140
|
+
'Prerequisites',
|
|
141
|
+
'State the required knowledge, access, environment and safe starting data before the reader begins.',
|
|
142
|
+
],
|
|
143
|
+
[
|
|
144
|
+
'Guided exercise',
|
|
145
|
+
'Walk through one complete learning exercise in order, explaining what each step demonstrates.',
|
|
146
|
+
],
|
|
147
|
+
[
|
|
148
|
+
'Expected result',
|
|
149
|
+
'Show how to recognize a successful exercise and compare the observed result with the learning goal.',
|
|
150
|
+
],
|
|
151
|
+
],
|
|
152
|
+
},
|
|
153
|
+
{
|
|
154
|
+
path: 'how-to',
|
|
155
|
+
title: 'How-to',
|
|
156
|
+
principle: 'One concrete reader task',
|
|
157
|
+
purpose: 'Readers who know their goal enter by task, confirm prerequisites and follow a bounded procedure.',
|
|
158
|
+
sections: [
|
|
159
|
+
[
|
|
160
|
+
'Prerequisites',
|
|
161
|
+
'State the required knowledge, access, environment and safe starting data before the reader begins.',
|
|
162
|
+
],
|
|
163
|
+
[
|
|
164
|
+
'Procedure',
|
|
165
|
+
'Give the ordered actions for one concrete task, including decision points and supported alternatives.',
|
|
166
|
+
],
|
|
167
|
+
[
|
|
168
|
+
'Verification and cleanup',
|
|
169
|
+
'Explain how to check the task result, remove temporary resources and recover from an incomplete attempt.',
|
|
170
|
+
],
|
|
171
|
+
],
|
|
172
|
+
},
|
|
173
|
+
{
|
|
174
|
+
path: 'reference',
|
|
175
|
+
title: 'Reference',
|
|
176
|
+
principle: 'Lookup by supported interface or contract',
|
|
177
|
+
purpose: 'Readers enter by a named interface or contract to find exact inputs, outputs, defaults and supported limits.',
|
|
178
|
+
sections: [
|
|
179
|
+
[
|
|
180
|
+
'Interfaces',
|
|
181
|
+
'Describe supported commands, APIs or configuration fields with their accepted inputs and observable outputs.',
|
|
182
|
+
],
|
|
183
|
+
[
|
|
184
|
+
'Defaults and limits',
|
|
185
|
+
'Record source-verified defaults, supported ranges and compatibility constraints for precise lookup.',
|
|
186
|
+
],
|
|
187
|
+
[
|
|
188
|
+
'Failure behavior',
|
|
189
|
+
'Describe errors, partial outcomes and recovery expectations for each supported interface.',
|
|
190
|
+
],
|
|
191
|
+
],
|
|
192
|
+
},
|
|
193
|
+
{
|
|
194
|
+
path: 'explanation',
|
|
195
|
+
title: 'Explanation',
|
|
196
|
+
principle: 'Understanding concepts and tradeoffs',
|
|
197
|
+
purpose: 'Readers enter by a concept or design question to understand relationships, constraints and tradeoffs.',
|
|
198
|
+
sections: [
|
|
199
|
+
[
|
|
200
|
+
'Concepts',
|
|
201
|
+
'Explain the vocabulary and mental models readers need before following task or reference pages.',
|
|
202
|
+
],
|
|
203
|
+
[
|
|
204
|
+
'Relationships',
|
|
205
|
+
'Show how the concepts and components depend on one another, linking their canonical contracts.',
|
|
206
|
+
],
|
|
207
|
+
[
|
|
208
|
+
'Tradeoffs',
|
|
209
|
+
'Explain design choices, alternatives and constraints, linking the decisions that establish them.',
|
|
210
|
+
],
|
|
211
|
+
],
|
|
212
|
+
},
|
|
213
|
+
],
|
|
214
|
+
'toolkit-cli': [
|
|
215
|
+
{
|
|
216
|
+
path: 'tools',
|
|
217
|
+
title: 'Tools',
|
|
218
|
+
principle: 'Tool, skill or command invocation',
|
|
219
|
+
purpose: 'Tool users enter by command or skill, confirm prerequisites and mutation scope, then inspect the expected output.',
|
|
220
|
+
sections: [
|
|
221
|
+
[
|
|
222
|
+
'Invocation',
|
|
223
|
+
'Document how to invoke each command or skill, including prerequisites and supported examples.',
|
|
224
|
+
],
|
|
225
|
+
[
|
|
226
|
+
'Inputs and side effects',
|
|
227
|
+
'Describe accepted arguments and configuration, mutation scope, required approval and external effects.',
|
|
228
|
+
],
|
|
229
|
+
[
|
|
230
|
+
'Outputs',
|
|
231
|
+
'Document result fields, generated artifacts, exit behavior and the next action each outcome supports.',
|
|
232
|
+
],
|
|
233
|
+
],
|
|
234
|
+
},
|
|
235
|
+
{
|
|
236
|
+
path: 'workflows',
|
|
237
|
+
title: 'Workflows',
|
|
238
|
+
principle: 'Reader goal across a sequence of tools',
|
|
239
|
+
purpose: 'Workflow users enter by their goal and follow an ordered sequence of tools with explicit authority and handoffs.',
|
|
240
|
+
sections: [
|
|
241
|
+
[
|
|
242
|
+
'Starting state',
|
|
243
|
+
'State the reader goal, required inputs, authority and ready signals before a workflow begins.',
|
|
244
|
+
],
|
|
245
|
+
[
|
|
246
|
+
'Sequence and handoffs',
|
|
247
|
+
'Order the tools and decisions, naming what each step passes to the next responsible actor.',
|
|
248
|
+
],
|
|
249
|
+
[
|
|
250
|
+
'Completion evidence',
|
|
251
|
+
'Define the observable result that closes the workflow and where to retain its execution evidence.',
|
|
252
|
+
],
|
|
253
|
+
],
|
|
254
|
+
},
|
|
255
|
+
],
|
|
256
|
+
'flat-small': [
|
|
257
|
+
{
|
|
258
|
+
path: 'start-here',
|
|
259
|
+
title: 'Start here',
|
|
260
|
+
principle: 'Reader goal in a flat grouped index',
|
|
261
|
+
purpose: 'Readers enter by their immediate goal, using one grouped index instead of navigating a hierarchy before choosing a task.',
|
|
262
|
+
sections: [
|
|
263
|
+
[
|
|
264
|
+
'Reader tasks',
|
|
265
|
+
'Group links by the immediate goals readers need to accomplish, keeping each procedure focused.',
|
|
266
|
+
],
|
|
267
|
+
[
|
|
268
|
+
'Reference',
|
|
269
|
+
'Link canonical interface and configuration facts for lookup without repeating them in task pages.',
|
|
270
|
+
],
|
|
271
|
+
[
|
|
272
|
+
'Operations',
|
|
273
|
+
'Link routine maintenance, diagnostic procedures and recovery runbooks, with their authority and safety boundaries.',
|
|
274
|
+
],
|
|
275
|
+
],
|
|
276
|
+
},
|
|
277
|
+
],
|
|
278
|
+
};
|
|
279
|
+
const SUPPORT_TEMPLATES = [
|
|
280
|
+
'alert-runbook',
|
|
281
|
+
'solution-record',
|
|
282
|
+
'command-reference',
|
|
283
|
+
'skill-command-guide',
|
|
284
|
+
'decisions-pointer',
|
|
285
|
+
'per-area-agents',
|
|
286
|
+
];
|
|
287
|
+
const TRIAD_TEMPLATES = [
|
|
288
|
+
'product-feature',
|
|
289
|
+
'engineering-feature',
|
|
290
|
+
'qa-validation',
|
|
291
|
+
'screen-spec',
|
|
292
|
+
...SUPPORT_TEMPLATES,
|
|
293
|
+
];
|
|
294
|
+
export function mergeTemplateExclusion(paths = []) {
|
|
295
|
+
return [...new Set([...paths, 'contributing/templates/**'])];
|
|
296
|
+
}
|
|
297
|
+
function page(title, description, body) {
|
|
298
|
+
return `---\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(description)}\n---\n\n# ${title}\n\n${body}\n`;
|
|
299
|
+
}
|
|
300
|
+
function link(title, path, description) {
|
|
301
|
+
return `- [${title}](${path}) - ${description}`;
|
|
302
|
+
}
|
|
303
|
+
/** Shared narrow content plan; bodies are loaded from the bundled canonical skill. */
|
|
304
|
+
export async function planPresetContent(options) {
|
|
305
|
+
const selection = resolvePresetSelection(options.iaPreset, options.plannedPages);
|
|
306
|
+
if (!selection.iaPreset)
|
|
307
|
+
return null;
|
|
308
|
+
const preset = selection.iaPreset;
|
|
309
|
+
const tracks = TRACKS[preset];
|
|
310
|
+
const flat = selection.plannedPages < 15 || preset === 'flat-small';
|
|
311
|
+
const files = [];
|
|
312
|
+
const rootLinks = [];
|
|
313
|
+
for (const track of tracks) {
|
|
314
|
+
const guideName = flat ? `${track.path}.md` : `${track.path}/start-here.md`;
|
|
315
|
+
const indexName = `${track.path}/index.md`;
|
|
316
|
+
const guideTitle = `${track.title}: choose a safe first task`;
|
|
317
|
+
const guide = `${track.purpose}\n\n## Choose the right contract\n\nIdentify your goal and supported environment before acting. Check availability, permissions and prerequisites in the repository's current source and reviewed guidance. A missing fact is a review gap, not permission to guess.\n\n## Establish a safe starting state\n\nPrefer an isolated example or read-only inspection. Record relevant configuration and inputs, avoid real personal data, and identify the owner of any external dependency. For changes, confirm approval and a cleanup or rollback route before proceeding.\n\n## Verify the result\n\nCompare the observable result with the supported contract. Keep concepts in prose; use backticks only for literals verified in source. Separate proposed automation, implemented test assertions and dated execution evidence. Escalate a discrepancy with the input, expected result and observed evidence.\n\n## Continue\n\nReturn to the [${flat ? 'documentation map' : `${track.title} map`}](index.md) to choose the next reader goal.\n`;
|
|
318
|
+
files.push({
|
|
319
|
+
name: guideName,
|
|
320
|
+
content: page(guideTitle, `Select prerequisites, boundaries and a verifiable first result for ${track.title.toLowerCase()} work.`, guide),
|
|
321
|
+
});
|
|
322
|
+
if (flat) {
|
|
323
|
+
rootLinks.push(`### ${track.title}\n\n${track.purpose}\n\n${link(guideTitle, guideName, 'Choose a safe starting state and verify the result.')}\n`);
|
|
324
|
+
}
|
|
325
|
+
else {
|
|
326
|
+
const sections = track.sections
|
|
327
|
+
.map(([title, guidance]) => `## ${title}\n\n${guidance}`)
|
|
328
|
+
.join('\n\n');
|
|
329
|
+
files.push({
|
|
330
|
+
name: indexName,
|
|
331
|
+
content: page(track.title, track.purpose, `${track.purpose}\n\nEntry principle: ${track.principle}. This track owns its canonical facts; route to shared contracts and paired pages rather than copying their claims.\n\n## Contents\n\n${link(guideTitle, 'start-here.md', 'Choose a safe starting state and verify the result.')}\n\n${sections}`),
|
|
332
|
+
});
|
|
333
|
+
rootLinks.push(link(track.title, indexName, track.purpose));
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
const contributor = options.markdown
|
|
337
|
+
? 'contributing.md'
|
|
338
|
+
: 'contributing/index.md';
|
|
339
|
+
rootLinks.push(`${flat ? '### Contributing\n\n' : ''}${link('Contributing', contributor, 'Authoring conventions and template selection.')}\n`);
|
|
340
|
+
files.unshift({
|
|
341
|
+
name: 'index.md',
|
|
342
|
+
content: page(options.siteName, options.siteDescription?.trim() ||
|
|
343
|
+
`Reader entry points for the ${preset} model.`, `Choose the entry matching your work context. This documentation uses the ${preset} reader model; its entry principles guide placement, while page count controls materialized depth. Confirm repository-specific behavior against source before acting.\n\n## Contents\n\n${rootLinks.join('\n')}`),
|
|
344
|
+
});
|
|
345
|
+
const templates = preset === 'product-engineering-qa'
|
|
346
|
+
? TRIAD_TEMPLATES
|
|
347
|
+
: preset === 'domain-engineering'
|
|
348
|
+
? ['engineering-feature', ...SUPPORT_TEMPLATES]
|
|
349
|
+
: SUPPORT_TEMPLATES;
|
|
350
|
+
for (const name of templates) {
|
|
351
|
+
files.push({
|
|
352
|
+
name: `contributing/templates/${name}.md`,
|
|
353
|
+
content: await readFile(join(options.assetsRoot, 'skills', 'authoring-docs', 'references', 'page-templates', `${name}.md`), 'utf8'),
|
|
354
|
+
});
|
|
355
|
+
}
|
|
356
|
+
const table = tracks
|
|
357
|
+
.map((track) => `| ${flat ? `index.md (group: ${track.title})` : `${track.path}/`} | ${track.title} | ${track.principle} |`)
|
|
358
|
+
.join('\n');
|
|
359
|
+
const guidance = `## Preset selection\n\nAccepted selection supplied to init: ${preset}; anticipated reader pages: ${selection.plannedPages}. ${flat ? 'Reader structure is collapsed into grouped root headings.' : 'Reader directories are materialized at 15 or more anticipated pages.'} Contributor, template and toolchain pages are outside this reader-page estimate.\n\n| Location | Reader track | Entry principle |\n| --- | --- | --- |\n${table}\n\n${tracks.map((t) => t.purpose).join('\n\n')}\n\nUse contributing/templates/ as non-reader drafting assets. Screen specs are conditional on several journeys sharing a screen; no screen page or per-track AGENTS file is created automatically. Preserve canonical facts and paired links. This selection is not a persisted IA decision: complete the existing explicit approval/adoption and record-ia flow before claiming an authored IA record or config mirror. It does not initialize project management. Existing surfaces route to analyze and individually approved apply; init never restructures them.\n`;
|
|
360
|
+
return { files, guidance };
|
|
361
|
+
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,mBAAmB,EAGxB,sBAAsB,EAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,mBAAmB,EAGxB,sBAAsB,EAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAW5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAkBxB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,YAAY,CAAC,EACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,GACR,eAAe,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AA0OD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAoC7E;AAwRD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAyET"}
|
|
@@ -9,6 +9,7 @@ import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
|
|
|
9
9
|
import { resolveAssetsRoot } from '../../../fs/assets.js';
|
|
10
10
|
import { atomicWriteJson, fileExists } from '../../../fs/io.js';
|
|
11
11
|
import { Command, Option } from 'commander';
|
|
12
|
+
import { mergeTemplateExclusion } from './content.js';
|
|
12
13
|
import { buildDocsCommands } from './docs-commands.js';
|
|
13
14
|
import { applyMarkdownDocsPlan, MarkdownDocsWriteError, planMarkdownDocs, validateMarkdownConfig, validateMarkdownTarget, } from './markdown.js';
|
|
14
15
|
import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
|
|
@@ -107,8 +108,27 @@ const DEFAULT_DEPENDENCIES = {
|
|
|
107
108
|
root: plan.targetDir,
|
|
108
109
|
tooling: 'markdown',
|
|
109
110
|
index: `${plan.targetDir}/index.md`,
|
|
111
|
+
...(options.iaPreset
|
|
112
|
+
? {
|
|
113
|
+
nonReaderPaths: mergeTemplateExclusion(latest.documentation?.nonReaderPaths),
|
|
114
|
+
}
|
|
115
|
+
: {}),
|
|
110
116
|
};
|
|
111
|
-
|
|
117
|
+
if (options.iaPreset) {
|
|
118
|
+
const configPath = join(context.cwd, '.oat/config.json');
|
|
119
|
+
const raw = (await fileExists(configPath))
|
|
120
|
+
? JSON.parse(await readFile(configPath, 'utf8'))
|
|
121
|
+
: latest;
|
|
122
|
+
await atomicWriteJson(configPath, {
|
|
123
|
+
...raw,
|
|
124
|
+
documentation: {
|
|
125
|
+
...raw.documentation,
|
|
126
|
+
...latest.documentation,
|
|
127
|
+
},
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
else
|
|
131
|
+
await writeOatConfig(context.cwd, latest);
|
|
112
132
|
report.configStatus = 'updated';
|
|
113
133
|
}
|
|
114
134
|
catch (error) {
|
|
@@ -145,6 +165,8 @@ const DEFAULT_DEPENDENCIES = {
|
|
|
145
165
|
enabled: options.rootPatch,
|
|
146
166
|
});
|
|
147
167
|
const config = await readOatConfig(context.cwd);
|
|
168
|
+
if (options.iaPreset)
|
|
169
|
+
result.documentationConfig.nonReaderPaths = mergeTemplateExclusion(config.documentation?.nonReaderPaths);
|
|
148
170
|
config.documentation = {
|
|
149
171
|
...config.documentation,
|
|
150
172
|
...result.documentationConfig,
|
|
@@ -250,6 +272,8 @@ async function runDocsInitCommand(context, options, dependencies) {
|
|
|
250
272
|
interactive: context.interactive,
|
|
251
273
|
acceptDefaults: options.yes ?? false,
|
|
252
274
|
providedFramework: options.framework,
|
|
275
|
+
providedIaPreset: options.iaPreset,
|
|
276
|
+
providedPlannedPages: options.plannedPages,
|
|
253
277
|
providedAdopt: options.adopt,
|
|
254
278
|
providedAppName: options.appName,
|
|
255
279
|
providedSiteName: options.siteName,
|
|
@@ -276,6 +300,11 @@ async function runDocsInitCommand(context, options, dependencies) {
|
|
|
276
300
|
}
|
|
277
301
|
const inapplicableOptions = [];
|
|
278
302
|
const existingConfig = await dependencies.readOatConfig(context.cwd);
|
|
303
|
+
if (resolved.iaPreset &&
|
|
304
|
+
(existingConfig.documentation?.root ||
|
|
305
|
+
existingConfig.documentation?.ia ||
|
|
306
|
+
existingConfig.documentation?.navOwner))
|
|
307
|
+
throw new Error('Preset init cannot replace an existing docs surface or navigation ownership. Use oat-docs-analyze and individually approved oat-docs-apply.');
|
|
279
308
|
if (resolved.framework === 'markdown') {
|
|
280
309
|
resolved.targetDir = await validateMarkdownTarget(context.cwd, resolved.targetDir);
|
|
281
310
|
validateMarkdownConfig(context.cwd, resolved.targetDir, existingConfig.documentation);
|
|
@@ -464,6 +493,8 @@ export function createDocsInitCommand(overrides = {}) {
|
|
|
464
493
|
.addOption(new Option('--app-name <name>', 'Docs app name (inapplicable to Markdown)'))
|
|
465
494
|
.addOption(new Option('--site-name <name>', 'Site display title or Markdown documentation title'))
|
|
466
495
|
.addOption(new Option('--target-dir <path>', 'Docs directory (Markdown defaults to docs; requires a dedicated directory)'))
|
|
496
|
+
.option('--ia-preset <preset>', 'Approved IA preset (requires --planned-pages; fresh empty target only)')
|
|
497
|
+
.option('--planned-pages <count>', 'Anticipated reader pages: integer >=1; collapse below 15 (requires --ia-preset)')
|
|
467
498
|
.addOption(new Option('--description <text>', 'Documentation description'))
|
|
468
499
|
.addOption(new Option('--lint <mode>', 'Markdown lint mode').choices([
|
|
469
500
|
'none',
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;
|
|
1
|
+
{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/markdown.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAMjE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAsBD,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,QAAQ,CAAC,MAAM,EAAE,kBAAkB;IAFrC,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,EACnC,KAAK,EAAE,OAAO,EAGf;CACF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,IAAI,CAeN;AA6JD,kEAAkE;AAClE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAuG3B;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA+E7B"}
|