@open-agent-toolkit/cli 0.0.31 → 0.0.33

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 (31) hide show
  1. package/README.md +7 -0
  2. package/assets/docs/cli-utilities/config-and-local-state.md +12 -4
  3. package/assets/docs/provider-sync/commands.md +13 -6
  4. package/assets/docs/provider-sync/index.md +2 -0
  5. package/assets/docs/provider-sync/instruction-sync.md +146 -0
  6. package/assets/docs/provider-sync/scope-and-surface.md +2 -2
  7. package/assets/docs/reference/cli-reference.md +1 -0
  8. package/assets/docs/reference/troubleshooting.md +10 -5
  9. package/assets/public-package-versions.json +4 -4
  10. package/assets/skills/oat-project-complete/SKILL.md +8 -30
  11. package/dist/commands/instructions/instructions.types.d.ts +17 -4
  12. package/dist/commands/instructions/instructions.types.d.ts.map +1 -1
  13. package/dist/commands/instructions/instructions.types.js +5 -1
  14. package/dist/commands/instructions/instructions.utils.d.ts +4 -2
  15. package/dist/commands/instructions/instructions.utils.d.ts.map +1 -1
  16. package/dist/commands/instructions/instructions.utils.js +238 -25
  17. package/dist/commands/instructions/sync/sync.d.ts +3 -1
  18. package/dist/commands/instructions/sync/sync.d.ts.map +1 -1
  19. package/dist/commands/instructions/sync/sync.js +176 -16
  20. package/dist/commands/instructions/validate/validate.d.ts +1 -1
  21. package/dist/commands/instructions/validate/validate.d.ts.map +1 -1
  22. package/dist/commands/instructions/validate/validate.js +16 -6
  23. package/dist/commands/project/complete-state/index.d.ts +16 -0
  24. package/dist/commands/project/complete-state/index.d.ts.map +1 -0
  25. package/dist/commands/project/complete-state/index.js +78 -0
  26. package/dist/commands/project/complete-state/state-utils.d.ts +7 -0
  27. package/dist/commands/project/complete-state/state-utils.d.ts.map +1 -0
  28. package/dist/commands/project/complete-state/state-utils.js +72 -0
  29. package/dist/commands/project/index.d.ts.map +1 -1
  30. package/dist/commands/project/index.js +2 -0
  31. package/package.json +2 -2
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  Open Agent Toolkit command-line interface for provider sync, docs tooling, workflow utilities, and diagnostics.
4
4
 
5
+ The CLI also supports project-scoped instruction sync for nested `AGENTS.md` / `CLAUDE.md` files, including pointer, symlink, and hard-copy repair strategies plus Claude-only adoption.
6
+
5
7
  ## Install
6
8
 
7
9
  ```bash
@@ -26,10 +28,13 @@ oat config describe
26
28
  Additional useful entry points:
27
29
 
28
30
  - `oat tools install`
31
+ - `oat instructions validate --strategy pointer`
32
+ - `oat instructions sync --dry-run --strategy symlink`
29
33
  - `oat docs init --app-name my-docs`
30
34
  - `oat config dump --json`
31
35
  - `oat project status --json`
32
36
  - `oat project list --json`
37
+ - `oat project complete-state /path/to/project`
33
38
  - `oat project archive sync`
34
39
  - `oat doctor`
35
40
 
@@ -40,6 +45,7 @@ Use these commands when you want structured runtime/project state out of the CLI
40
45
  - `oat config dump --json` - emit merged OAT config with per-key source attribution
41
46
  - `oat project status --json` - emit the active project's full parsed control-plane state
42
47
  - `oat project list --json` - emit summary state for tracked projects under the configured projects root
48
+ - `oat project complete-state <project-path>` - emit the canonical completed lifecycle shape into a tracked project's `state.md`
43
49
 
44
50
  ## Requirements
45
51
 
@@ -50,4 +56,5 @@ Use these commands when you want structured runtime/project state out of the CLI
50
56
  - [Docs Home](https://voxmedia.github.io/open-agent-toolkit/)
51
57
  - [CLI Utilities](https://voxmedia.github.io/open-agent-toolkit/cli-utilities)
52
58
  - [Provider Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync)
59
+ - [Instruction Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync/instruction-sync)
53
60
  - [Reference](https://voxmedia.github.io/open-agent-toolkit/reference)
package/assets/docs/cli-utilities/config-and-local-state.md CHANGED
@@ -80,12 +80,20 @@ Use these reference pages for file ownership and schema details:
80
80
 
81
81
  ## `oat instructions ...`
82
82
 
83
- These commands validate and repair pointer integrity between `AGENTS.md` and sibling `CLAUDE.md` files.
83
+ These commands validate and repair project-scoped instruction integrity between `AGENTS.md` and sibling `CLAUDE.md` files.
84
84
 
85
- - `oat instructions validate` - read-only integrity check
86
- - `oat instructions sync` - preview or apply pointer repairs
85
+ - `oat instructions validate` - read-only integrity check with `--strategy pointer|symlink|copy`
86
+ - `oat instructions sync` - preview or apply pointer, symlink, or hard-copy repairs
87
87
 
88
- Use this command group when instruction files drift after manual edits or generated updates.
88
+ Use this command group when instruction files drift after manual edits or generated updates, or when nested project directories contain Claude-only stray files that should be adopted into canonical `AGENTS.md`.
89
+
90
+ Operational notes:
91
+
92
+ - Validation and sync use the same recursive scan model, so `--dry-run` previews the same states that `validate` reports.
93
+ - `pointer` is the default strategy; `symlink` and `copy` make file shape part of correctness.
94
+ - Unreadable canonical `AGENTS.md` files and unreadable Claude-only sources are surfaced as drift, but sync leaves them in manual-repair mode instead of guessing at recovery.
95
+
96
+ For the full state model, repair semantics, and examples, see [Instruction Sync](../provider-sync/instruction-sync.md).
89
97
 
90
98
  ## Repo state helpers
91
99
 
package/assets/docs/provider-sync/commands.md CHANGED
@@ -84,23 +84,30 @@ These commands are documented here because they are commonly used during interop
84
84
 
85
85
  Purpose:
86
86
 
87
- - Validate AGENTS.md to CLAUDE.md pointer integrity
87
+ - Validate project-scoped `AGENTS.md` to `CLAUDE.md` integrity
88
88
 
89
89
  Key behavior:
90
90
 
91
- - Read-only validation of sibling `CLAUDE.md` pointer files for each discovered `AGENTS.md`
92
- - Reports `ok`, `missing`, and `content_mismatch` states
91
+ - Read-only validation of nested project-scoped instruction directories
92
+ - Supports `--strategy pointer|symlink|copy` to validate the expected file shape
93
+ - Reports `ok`, `missing`, `content_mismatch`, and `stray` states
94
+ - Detects Claude-only adoptable directories and unreadable/broken instruction paths as drift
93
95
  - Exit code `0` when all entries are valid, `1` when drift is detected
96
+ - Detailed behavior: [`Instruction Sync`](instruction-sync.md)
94
97
 
95
98
  ## `oat instructions sync`
96
99
 
97
100
  Purpose:
98
101
 
99
- - Repair AGENTS.md to CLAUDE.md pointer drift
102
+ - Repair project-scoped `AGENTS.md` to `CLAUDE.md` drift
100
103
 
101
104
  Key behavior:
102
105
 
103
106
  - Mutates by default; use `--dry-run` to preview changes
104
- - Creates missing `CLAUDE.md` pointers
107
+ - Supports `--strategy pointer|symlink|copy`
108
+ - Creates missing `CLAUDE.md` files using the selected strategy
109
+ - Adopts Claude-only stray files by writing canonical `AGENTS.md` content first, then regenerating `CLAUDE.md`
105
110
  - Skips mismatched files unless `--force` is provided
106
- - Writes canonical pointer content `@AGENTS.md\n`
111
+ - Skips unreadable canonical or Claude-only sources and reports manual-repair guidance instead of forcing recovery
112
+ - Uses pointer content `@AGENTS.md\n`, file symlinks, or hard copies depending on the selected strategy
113
+ - Detailed behavior and examples: [`Instruction Sync`](instruction-sync.md)
package/assets/docs/provider-sync/index.md CHANGED
@@ -28,6 +28,7 @@ This section explains how OAT treats `.agents/` and `.oat/` as the source of tru
28
28
  ## Common Tasks
29
29
 
30
30
  - Understand the canonical/provider-view model in [Scope and Surface](scope-and-surface.md).
31
+ - Manage nested `AGENTS.md` / `CLAUDE.md` integrity in [Instruction Sync](instruction-sync.md).
31
32
  - Learn provider-specific mappings in [Providers](providers.md).
32
33
  - Diagnose drift and adoption behavior in [Manifest and Drift](manifest-and-drift.md).
33
34
  - Adjust provider enablement and scope behavior in [Sync Config](config.md).
@@ -38,6 +39,7 @@ This section explains how OAT treats `.agents/` and `.oat/` as the source of tru
38
39
  - [CLI Bootstrap](../cli-utilities/bootstrap.md) - Foundational setup before first sync.
39
40
  - [Scope and Surface](scope-and-surface.md) - Canonical assets, provider views, scopes, and the sync surface area.
40
41
  - [Commands](commands.md) - `oat status`, `oat sync`, and `oat providers ...` behavior.
42
+ - [Instruction Sync](instruction-sync.md) - Project-scoped `AGENTS.md` / `CLAUDE.md` validation, repair, and Claude-only adoption.
41
43
  - [Providers](providers.md) - Provider-specific mappings, capabilities, and path conventions.
42
44
  - [Manifest and Drift](manifest-and-drift.md) - How OAT tracks synced state, stray files, and adoption decisions.
43
45
  - [Sync Config](config.md) - Provider config model, enablement, and scope semantics.
package/assets/docs/provider-sync/instruction-sync.md ADDED
@@ -0,0 +1,146 @@
1
+ ---
2
+ title: Instruction Sync
3
+ description: Project-scoped AGENTS.md and CLAUDE.md validation, repair strategies, and Claude-only adoption.
4
+ ---
5
+
6
+ # Instruction Sync
7
+
8
+ `oat instructions ...` is the project-scoped lane for keeping canonical `AGENTS.md` files aligned with sibling `CLAUDE.md` files throughout a repository tree.
9
+
10
+ Use it when you want OAT to:
11
+
12
+ - validate nested `AGENTS.md` / `CLAUDE.md` pairs
13
+ - repair missing or drifted `CLAUDE.md` files with a chosen strategy
14
+ - adopt Claude-only directories back into canonical `AGENTS.md`
15
+
16
+ This command group is intentionally separate from manifest-backed provider sync. It operates on repo-local instruction files, not provider view manifests.
17
+
18
+ ## Scope
19
+
20
+ Instruction sync is currently project-only.
21
+
22
+ - It scans the current repository recursively.
23
+ - It supports nested directories all the way down the tree.
24
+ - It skips provider-irrelevant or local-only roots such as `.git`, `.oat`, `.worktrees`, and `node_modules`.
25
+ - It does not scan user-level provider roots such as `~/.claude` in this release.
26
+
27
+ ## Canonical Model
28
+
29
+ - `AGENTS.md` is canonical.
30
+ - `CLAUDE.md` is derived from the sibling `AGENTS.md`.
31
+ - If a directory contains only `CLAUDE.md`, OAT can adopt that file by writing canonical `AGENTS.md` content first and then regenerating `CLAUDE.md`.
32
+
33
+ ## Commands
34
+
35
+ ### `oat instructions validate`
36
+
37
+ Read-only validation for instruction integrity.
38
+
39
+ - Resolves the project root automatically.
40
+ - Scans nested directories for instruction pairs and Claude-only strays.
41
+ - Returns exit code `0` when everything is valid and `1` when drift is detected.
42
+ - Suggests the matching repair command, including `--strategy` when you validated with a non-default mode.
43
+
44
+ ### `oat instructions sync`
45
+
46
+ Repair and adoption command for instruction drift.
47
+
48
+ - Mutates by default.
49
+ - Use `--dry-run` to preview planned actions.
50
+ - Use `--force` to overwrite mismatched `CLAUDE.md` files.
51
+ - Reuses the selected strategy when creating or repairing `CLAUDE.md`.
52
+
53
+ ## Supported Strategies
54
+
55
+ `CLAUDE.md` can be generated or validated in one of three modes:
56
+
57
+ | Strategy | Expected `CLAUDE.md` shape | Notes |
58
+ | --------- | -------------------------------- | --------------------------------------- |
59
+ | `pointer` | file content `@AGENTS.md` | Default mode. Lightweight and explicit. |
60
+ | `symlink` | file symlink to `AGENTS.md` | Uses a same-directory relative symlink. |
61
+ | `copy` | hard copy of `AGENTS.md` content | Useful when symlinks are undesirable. |
62
+
63
+ Validation treats the selected file shape as part of correctness. For example, `copy` mode rejects a symlink even if the symlink resolves to identical content.
64
+
65
+ ## Reported States
66
+
67
+ `oat instructions validate` and `oat instructions sync --dry-run` work from the same scan model.
68
+
69
+ | State | Meaning |
70
+ | ------------------ | ------------------------------------------------------------------------------------------------ |
71
+ | `ok` | The discovered instruction pair matches the selected strategy. |
72
+ | `missing` | `AGENTS.md` exists but sibling `CLAUDE.md` is missing. |
73
+ | `content_mismatch` | `CLAUDE.md` exists but has the wrong shape/content, or an instruction file is unreadable/broken. |
74
+ | `stray` | `CLAUDE.md` exists without sibling `AGENTS.md` and the Claude file is readable enough to adopt. |
75
+
76
+ ## Claude-Only Adoption
77
+
78
+ When a directory contains `CLAUDE.md` but no `AGENTS.md`, sync can adopt it:
79
+
80
+ 1. Read the existing `CLAUDE.md`
81
+ 2. Write canonical `AGENTS.md` with that content
82
+ 3. Regenerate `CLAUDE.md` using the selected strategy
83
+
84
+ This means the original Claude instructions become canonical before the derived file is rewritten.
85
+
86
+ Readable Claude-only files are adoptable. Unreadable Claude-only files are not.
87
+
88
+ ## When `--force` Is Required
89
+
90
+ `oat instructions sync` does not overwrite a mismatched `CLAUDE.md` unless you pass `--force`.
91
+
92
+ Typical pattern:
93
+
94
+ ```bash
95
+ oat instructions validate --strategy symlink
96
+ oat instructions sync --dry-run --strategy symlink
97
+ oat instructions sync --force --strategy symlink
98
+ oat instructions validate --strategy symlink
99
+ ```
100
+
101
+ This keeps validation, preview, and repair aligned to the same expected file shape.
102
+
103
+ ## Manual-Repair Cases
104
+
105
+ Some states are intentionally surfaced as drift but not auto-repaired.
106
+
107
+ Examples:
108
+
109
+ - unreadable canonical `AGENTS.md`
110
+ - broken or unreadable `AGENTS.md` symlink targets
111
+ - unreadable Claude-only sources
112
+ - broken or unreadable paired `CLAUDE.md` symlink targets
113
+
114
+ In these cases, sync reports a manual-repair skip instead of guessing at destructive recovery.
115
+
116
+ ## Example Workflow
117
+
118
+ Preview and adopt nested Claude-only strays as pointer files:
119
+
120
+ ```bash
121
+ oat instructions sync --dry-run
122
+ oat instructions sync
123
+ ```
124
+
125
+ Validate and repair everything as symlinks:
126
+
127
+ ```bash
128
+ oat instructions validate --strategy symlink
129
+ oat instructions sync --dry-run --strategy symlink
130
+ oat instructions sync --force --strategy symlink
131
+ ```
132
+
133
+ Validate and repair everything as hard copies:
134
+
135
+ ```bash
136
+ oat instructions validate --strategy copy
137
+ oat instructions sync --dry-run --strategy copy
138
+ oat instructions sync --force --strategy copy
139
+ ```
140
+
141
+ ## Related Pages
142
+
143
+ - [Provider Interop Commands](commands.md)
144
+ - [Provider Interop CLI Scope and Surface](scope-and-surface.md)
145
+ - [Config and Local State](../cli-utilities/config-and-local-state.md)
146
+ - [Troubleshooting](../reference/troubleshooting.md)
package/assets/docs/provider-sync/scope-and-surface.md CHANGED
@@ -7,7 +7,7 @@ description: 'Scope boundaries and design principles for canonical-to-provider a
7
7
 
8
8
  The provider interop CLI in `packages/cli` manages canonical agent assets under `.agents/` and reconciles provider-specific views.
9
9
 
10
- This capability is intentionally independent from OAT workflow artifacts. Teams can adopt provider interoperability usage (`status`, `sync`, `providers ...`) plus optional instruction-pointer integrity checks (`instructions validate/sync`) without using discovery/spec/design/plan/implement project workflows.
10
+ This capability is intentionally independent from OAT workflow artifacts. Teams can adopt provider interoperability usage (`status`, `sync`, `providers ...`) plus optional project-scoped instruction sync integrity checks (`instructions validate/sync`) without using discovery/spec/design/plan/implement project workflows.
11
11
 
12
12
  ## Scope
13
13
 
@@ -53,7 +53,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
53
53
  ## Non-interop namespaces in the same CLI
54
54
 
55
55
  - `oat project new <name>` (workflow/project scaffolding)
56
- - `oat instructions validate` / `oat instructions sync` (AGENTS.md to CLAUDE.md pointer integrity)
56
+ - `oat instructions validate` / `oat instructions sync` (AGENTS.md/CLAUDE.md pointer, symlink, or copy integrity plus Claude-only adoption)
57
57
  - `oat internal validate-oat-skills` (internal maintenance)
58
58
 
59
59
  ## Reference artifacts
package/assets/docs/reference/cli-reference.md CHANGED
@@ -39,6 +39,7 @@ Notable inspection commands introduced in the current CLI surface:
39
39
  - `oat config dump --json` - merged config with source attribution
40
40
  - `oat project status --json` - full parsed state for the active tracked project
41
41
  - `oat project list --json` - summary state for tracked projects under the configured projects root
42
+ - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
42
43
 
43
44
  ## `oat config` surface flags
44
45
 
package/assets/docs/reference/troubleshooting.md CHANGED
@@ -27,13 +27,18 @@ Expected for native-read skill mappings. Codex can read canonical skills without
27
27
  - `oat providers set --scope project --enabled <providers> --disabled <providers>`
28
28
  - Re-run `oat sync --scope project` after updating config.
29
29
 
30
- ## `instructions validate` reports `missing` or `content_mismatch`
31
-
32
- - Run `oat instructions sync` to preview changes.
33
- - Run `oat instructions sync` to create missing pointer files.
34
- - If mismatched `CLAUDE.md` files should be overwritten, run `oat instructions sync --force`.
30
+ ## `instructions validate` reports `missing`, `content_mismatch`, or `stray`
31
+
32
+ - Run `oat instructions sync --dry-run` to preview changes.
33
+ - Run `oat instructions sync --strategy pointer|symlink|copy` to apply the expected `CLAUDE.md` shape.
34
+ - If mismatched `CLAUDE.md` files should be overwritten, run `oat instructions sync --force` (or combine it with `--strategy` if needed).
35
+ - If `stray` is reported, `oat instructions sync` will adopt the Claude-only file into `AGENTS.md` and then regenerate `CLAUDE.md`.
36
+ - If a broken or unreadable instruction path is reported, fix the underlying file or symlink target first; sync will intentionally skip manual-repair cases instead of forcing recovery.
37
+ - If a directory you expected to see is missing from the scan, confirm it is not under `.git`, `.oat`, `.worktrees`, or `node_modules`.
35
38
  - Re-run `oat instructions validate` and confirm status is `ok`.
36
39
 
40
+ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strategy matrix and state model.
41
+
37
42
  ## `doctor` warns about canonical directories
38
43
 
39
44
  - Run `oat init` for the relevant scope.
package/assets/public-package-versions.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
- "cli": "0.0.31",
3
- "docs-config": "0.0.31",
4
- "docs-theme": "0.0.31",
5
- "docs-transforms": "0.0.31"
2
+ "cli": "0.0.33",
3
+ "docs-config": "0.0.33",
4
+ "docs-theme": "0.0.33",
5
+ "docs-transforms": "0.0.33"
6
6
  }
package/assets/skills/oat-project-complete/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-complete
3
- version: 1.4.0
3
+ version: 1.4.1
4
4
  description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -254,41 +254,19 @@ Rules:
254
254
 
255
255
  ### Step 5: Set Lifecycle Complete
256
256
 
257
- Update `state.md` frontmatter to add/update `oat_lifecycle: complete` and set completion timestamps:
257
+ Delegate the canonical `state.md` completion mutation to the CLI:
258
258
 
259
259
  ```bash
260
- STATE_FILE="${PROJECT_PATH}/state.md"
261
- NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
262
-
263
- # Check if oat_lifecycle already exists
264
- if grep -q "^oat_lifecycle:" "$STATE_FILE"; then
265
- # Update existing (portable approach using temp file)
266
- sed 's/^oat_lifecycle:.*/oat_lifecycle: complete/' "$STATE_FILE" > "$STATE_FILE.tmp"
267
- mv "$STATE_FILE.tmp" "$STATE_FILE"
268
- else
269
- # Add after oat_phase_status line using awk (more portable for multi-line inserts)
270
- awk '/^oat_phase_status:/ {print; print "oat_lifecycle: complete"; next} 1' "$STATE_FILE" > "$STATE_FILE.tmp"
271
- mv "$STATE_FILE.tmp" "$STATE_FILE"
260
+ COMPLETE_STATE_ARGS=("$PROJECT_PATH")
261
+ if [[ "$SHOULD_ARCHIVE" == "true" && "$IS_SHARED_PROJECT" == "true" ]]; then
262
+ COMPLETE_STATE_ARGS+=("--archived")
272
263
  fi
273
264
 
274
- # Set completion and state-updated timestamps
275
- sed -E "s/^oat_project_completed:.*/oat_project_completed: \"$NOW_UTC\"/" "$STATE_FILE" > "$STATE_FILE.tmp"
276
- mv "$STATE_FILE.tmp" "$STATE_FILE"
277
- sed -E "s/^oat_project_state_updated:.*/oat_project_state_updated: \"$NOW_UTC\"/" "$STATE_FILE" > "$STATE_FILE.tmp"
278
- mv "$STATE_FILE.tmp" "$STATE_FILE"
265
+ oat project complete-state "${COMPLETE_STATE_ARGS[@]}"
279
266
  ```
280
267
 
281
- Then update the markdown body in `state.md` so the completion state is explicit and does not rely on reference lookups:
282
-
283
- - Set `**Status:** Complete`
284
- - Set `**Last Updated:**` to the completion date in `YYYY-MM-DD`
285
- - In `## Current Phase`, replace the body with:
286
- - `Lifecycle complete; archived locally` when the project is archived in Step 8
287
- - `Lifecycle complete` when the project is completed without archive
288
- - In `## Progress`, preserve the existing completed workflow/review bullets and add `- ✓ Project lifecycle complete` if it is not already present
289
- - In `## Next Milestone`, replace the body with `None. Project complete.`
290
-
291
- Do not infer these body mutations from other archived projects. Apply them directly as part of this skill.
268
+ The CLI command owns both the frontmatter completion fields and the canonical markdown body updates for `state.md`.
269
+ It must set `oat_lifecycle: complete`, completion timestamps, `**Status:** Complete`, `**Last Updated:**`, the canonical `## Current Phase` body, normalized `## Progress`, and `## Next Milestone`.
292
270
 
293
271
  ### Step 6: Clear Active Project Pointer
294
272
 
package/dist/commands/instructions/instructions.types.d.ts CHANGED
@@ -1,9 +1,11 @@
1
1
  import type { Dirent, Stats } from 'node:fs';
2
2
  import type { CommandContext, GlobalOptions } from '../../app/command-context.js';
3
- export type InstructionStatus = 'ok' | 'missing' | 'content_mismatch';
3
+ export declare const INSTRUCTION_SYNC_STRATEGIES: readonly ["pointer", "symlink", "copy"];
4
+ export type InstructionSyncStrategy = (typeof INSTRUCTION_SYNC_STRATEGIES)[number];
5
+ export type InstructionStatus = 'ok' | 'missing' | 'content_mismatch' | 'stray';
4
6
  export type InstructionsStatus = 'ok' | 'drift';
5
7
  export interface InstructionEntry {
6
- agentsPath: string;
8
+ agentsPath: string | null;
7
9
  claudePath: string;
8
10
  status: InstructionStatus;
9
11
  detail: string;
@@ -22,6 +24,7 @@ export interface InstructionsSummary {
22
24
  ok: number;
23
25
  missing: number;
24
26
  contentMismatch: number;
27
+ stray: number;
25
28
  created: number;
26
29
  updated: number;
27
30
  skipped: number;
@@ -33,20 +36,30 @@ export interface InstructionsJsonPayload {
33
36
  entries: InstructionEntry[];
34
37
  actions: InstructionActionRecord[];
35
38
  }
39
+ export interface InstructionsScanOptions {
40
+ strategy?: InstructionSyncStrategy;
41
+ debug?: (message: string) => void;
42
+ }
36
43
  export interface InstructionsScanDependencies {
37
44
  readdir: (path: string, options: {
38
45
  withFileTypes: true;
39
46
  }) => Promise<Dirent[]>;
47
+ lstat: (path: string) => Promise<Stats>;
48
+ realpath: (path: string) => Promise<string>;
40
49
  readFile: (path: string, encoding: 'utf8') => Promise<string>;
50
+ readlink: (path: string) => Promise<string>;
41
51
  stat: (path: string) => Promise<Stats>;
42
- debug?: (message: string) => void;
43
52
  }
44
53
  export interface InstructionsValidateCommandDependencies {
45
54
  buildCommandContext: (options: GlobalOptions) => CommandContext;
46
55
  resolveProjectRoot: (cwd: string) => Promise<string>;
47
- scanInstructionFiles: (repoRoot: string, overrides?: Partial<InstructionsScanDependencies>) => Promise<InstructionEntry[]>;
56
+ scanInstructionFiles: (repoRoot: string, options?: InstructionsScanOptions, overrides?: Partial<InstructionsScanDependencies>) => Promise<InstructionEntry[]>;
48
57
  }
49
58
  export interface InstructionsSyncCommandDependencies extends InstructionsValidateCommandDependencies {
59
+ lstat: (path: string) => Promise<Stats>;
60
+ readFile: (path: string, encoding: 'utf8') => Promise<string>;
61
+ removeFile: (path: string) => Promise<void>;
62
+ symlinkFile: (target: string, path: string) => Promise<void>;
50
63
  writeFile: (path: string, content: string, encoding: 'utf8') => Promise<void>;
51
64
  }
52
65
  //# sourceMappingURL=instructions.types.d.ts.map
package/dist/commands/instructions/instructions.types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"instructions.types.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,KAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,uCAAuC;IACtD,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,oBAAoB,EAAE,CACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,OAAO,CAAC,4BAA4B,CAAC,KAC9C,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,mCAAoC,SAAQ,uCAAuC;IAClG,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E"}
1
+ {"version":3,"file":"instructions.types.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.types.ts"],"names":[],"mappings":"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"}
package/dist/commands/instructions/instructions.types.js CHANGED
@@ -1 +1,5 @@
1
- export {};
1
+ export const INSTRUCTION_SYNC_STRATEGIES = [
2
+ 'pointer',
3
+ 'symlink',
4
+ 'copy',
5
+ ];
package/dist/commands/instructions/instructions.utils.d.ts CHANGED
@@ -1,11 +1,13 @@
1
- import type { InstructionActionRecord, InstructionEntry, InstructionsJsonPayload, InstructionsMode, InstructionsScanDependencies, InstructionsSummary } from './instructions.types.js';
1
+ import type { InstructionSyncStrategy, InstructionActionRecord, InstructionEntry, InstructionsJsonPayload, InstructionsMode, InstructionsScanOptions, InstructionsScanDependencies, InstructionsSummary } from './instructions.types.js';
2
2
  export declare const EXPECTED_CLAUDE_CONTENT = "@AGENTS.md\n";
3
+ export declare const DEFAULT_INSTRUCTION_SYNC_STRATEGY: InstructionSyncStrategy;
3
4
  interface BuildInstructionsPayloadArgs {
4
5
  mode: InstructionsMode;
5
6
  entries: InstructionEntry[];
6
7
  actions: InstructionActionRecord[];
7
8
  }
8
- export declare function scanInstructionFiles(repoRoot: string, overrides?: Partial<InstructionsScanDependencies>): Promise<InstructionEntry[]>;
9
+ export declare function resolveInstructionSyncStrategy(strategy?: InstructionSyncStrategy): InstructionSyncStrategy;
10
+ export declare function scanInstructionFiles(repoRoot: string, options?: InstructionsScanOptions, overrides?: Partial<InstructionsScanDependencies>): Promise<InstructionEntry[]>;
9
11
  export declare function buildInstructionsSummary(entries: InstructionEntry[], actions: InstructionActionRecord[]): InstructionsSummary;
10
12
  export declare function buildInstructionsPayload({ mode, entries, actions, }: BuildInstructionsPayloadArgs): InstructionsJsonPayload;
11
13
  export declare function formatInstructionsReport(payload: InstructionsJsonPayload, repoRoot?: string): string;
package/dist/commands/instructions/instructions.utils.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAKtD,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAoHD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoD7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAmBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAkCR"}
1
+ {"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAKZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAqBD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AAoLD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}