@dypt/cli 0.1.2 → 0.1.4

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 CHANGED
@@ -71,6 +71,35 @@ dypt task list --limit 10 --json
71
71
  dypt task get 123 --json
72
72
  ```
73
73
 
74
+ ## Agent guidance
75
+
76
+ Install or inspect dypt agent guidance for supported AI coding tools:
77
+
78
+ ```bash
79
+ dypt agent status
80
+ dypt agent install codex
81
+ dypt agent install claude
82
+ ```
83
+
84
+ By default, `dypt agent install` installs the latest released `dypt-cli` skill
85
+ from the public [`poyzer-tech/dypt-toolkit`](https://github.com/poyzer-tech/dypt-toolkit)
86
+ repository. It is safe to rerun: missing installs are created, managed
87
+ unmodified installs are updated, and locally modified installs require an
88
+ explicit `--backup` or `--force`.
89
+
90
+ For development or testing, install from a local toolkit checkout:
91
+
92
+ ```bash
93
+ dypt agent install codex --source local --path /path/to/dypt-toolkit --dry-run
94
+ ```
95
+
96
+ Print repo-level `AGENTS.md` / `CLAUDE.md` guidance, or append it explicitly:
97
+
98
+ ```bash
99
+ dypt agent install-instructions
100
+ dypt agent install-instructions --append AGENTS.md
101
+ ```
102
+
74
103
  ## Support policy
75
104
 
76
105
  - the CLI is currently versioned as an early `0.x` release, so command shape and
package/dist/index.js CHANGED
@@ -4,12 +4,12 @@
4
4
  import { realpathSync } from "fs";
5
5
  import { fileURLToPath, pathToFileURL } from "url";
6
6
  import { createInterface } from "readline/promises";
7
- import { Command, Option } from "commander";
7
+ import { Argument, Command, Option } from "commander";
8
8
 
9
9
  // package.json
10
10
  var package_default = {
11
11
  name: "@dypt/cli",
12
- version: "0.1.2",
12
+ version: "0.1.4",
13
13
  description: "Command-line interface for dypt task management",
14
14
  license: "SEE LICENSE IN LICENSE",
15
15
  homepage: "https://dypt.app",
@@ -251,8 +251,8 @@ async function createCliTrpcClient(options = {}) {
251
251
  ]
252
252
  });
253
253
  }
254
- async function postJson(path3, body, options = {}) {
255
- const response = await fetch(new URL(path3, resolveBaseUrl(options.baseUrl)), {
254
+ async function postJson(path4, body, options = {}) {
255
+ const response = await fetch(new URL(path4, resolveBaseUrl(options.baseUrl)), {
256
256
  method: "POST",
257
257
  headers: {
258
258
  "content-type": "application/json"
@@ -381,6 +381,383 @@ async function runLogout(deps = createDefaultLogoutDeps()) {
381
381
  deps.writeLine?.("Signed out of dypt CLI.");
382
382
  }
383
383
 
384
+ // src/lib/agentToolkit.ts
385
+ import { createHash } from "crypto";
386
+ import {
387
+ cp,
388
+ mkdir as mkdir2,
389
+ mkdtemp,
390
+ readFile as readFile2,
391
+ readdir,
392
+ rm as rm2,
393
+ stat,
394
+ writeFile as writeFile2
395
+ } from "fs/promises";
396
+ import os2 from "os";
397
+ import path3 from "path";
398
+ var TOOLKIT_REPO = "poyzer-tech/dypt-toolkit";
399
+ var SKILL_RELATIVE_PATH = path3.join("skills", "dypt-cli");
400
+ var METADATA_FILE = ".dypt-install.json";
401
+ var REQUIRED_FILES = [
402
+ "SKILL.md",
403
+ path3.join("agents", "openai.yaml"),
404
+ path3.join("references", "cli-basics.md")
405
+ ];
406
+ var AGENT_INSTRUCTIONS_APPEND_HINT = "To append these instructions to a repo agent file, run: dypt agent install-instructions --append AGENTS.md or dypt agent install-instructions --append CLAUDE.md";
407
+ var AGENT_INSTRUCTIONS_SNIPPET = `## Work Tracking with dypt
408
+
409
+ This project uses dypt tasks as the canonical work tracker. Use the dypt CLI
410
+ before creating, changing, or reporting on repo work.
411
+
412
+ ### Getting Started
413
+
414
+ Check that the CLI is available and authenticated:
415
+
416
+ \`\`\`bash
417
+ dypt --version
418
+ dypt auth status
419
+ \`\`\`
420
+
421
+ If the CLI is missing, install it with:
422
+
423
+ \`\`\`bash
424
+ npm install -g @dypt/cli
425
+ \`\`\`
426
+
427
+ If the dypt CLI skill is not available in this agent session, tell the user and
428
+ offer to install it:
429
+
430
+ \`\`\`bash
431
+ dypt agent install codex
432
+ dypt agent install claude
433
+ \`\`\`
434
+
435
+ When working on repo tasks:
436
+
437
+ - Use the dypt CLI to inspect tasks, notes, children, dependencies, and nearby branch context before changing work.
438
+ - Search before creating new tasks to avoid duplicates.
439
+ - If the right parent or scope for a new or moved task is not clear, ask the user to confirm before changing task structure.
440
+ - Capture durable context in dypt notes.
441
+ - Format longer dypt notes with appropriate markdown so they are readable and well presented.
442
+ - When referencing tasks in dypt notes, use dypt task links such as [#123](#task-123) and do not repeat the task title after the link.
443
+ - When referring to tasks back to the user, include both id and title, for example #123 Add CLI docs.
444
+ - Track follow-up work as dypt tasks.
445
+ - Do not create a parallel markdown TODO tracker.
446
+ - Do not set leaf tasks to in progress; dypt derives in progress for parent tasks from child state.
447
+ - Preview cleanup or bulk changes before applying them when preview is available.
448
+ - If the dypt-cli skill is available, use it for dypt task workflows.
449
+ `;
450
+ function metadataPath(targetPath) {
451
+ return path3.join(targetPath, METADATA_FILE);
452
+ }
453
+ async function pathExists(filePath) {
454
+ try {
455
+ await stat(filePath);
456
+ return true;
457
+ } catch (error) {
458
+ if (error.code === "ENOENT") {
459
+ return false;
460
+ }
461
+ throw error;
462
+ }
463
+ }
464
+ async function listFilesRecursive(root, prefix = "") {
465
+ const dir = path3.join(root, prefix);
466
+ const entries = await readdir(dir, { withFileTypes: true });
467
+ const files = await Promise.all(
468
+ entries.map(async (entry) => {
469
+ const relativePath = path3.join(prefix, entry.name);
470
+ if (relativePath === METADATA_FILE) return [];
471
+ if (entry.isDirectory()) {
472
+ return listFilesRecursive(root, relativePath);
473
+ }
474
+ if (entry.isFile()) {
475
+ return [relativePath];
476
+ }
477
+ return [];
478
+ })
479
+ );
480
+ return files.flat().sort();
481
+ }
482
+ async function hashFile(filePath) {
483
+ const content = await readFile2(filePath);
484
+ return createHash("sha256").update(content).digest("hex");
485
+ }
486
+ async function hashManagedFiles(root) {
487
+ const files = await listFilesRecursive(root);
488
+ const entries = await Promise.all(
489
+ files.map(async (file) => [file, await hashFile(path3.join(root, file))])
490
+ );
491
+ return Object.fromEntries(entries);
492
+ }
493
+ async function readMetadata(targetPath) {
494
+ try {
495
+ return JSON.parse(await readFile2(metadataPath(targetPath), "utf8"));
496
+ } catch (error) {
497
+ if (error.code === "ENOENT") {
498
+ return null;
499
+ }
500
+ throw error;
501
+ }
502
+ }
503
+ function hashesMatch(current, previous) {
504
+ const currentKeys = Object.keys(current).sort();
505
+ const previousKeys = Object.keys(previous).sort();
506
+ if (currentKeys.length !== previousKeys.length) return false;
507
+ return currentKeys.every(
508
+ (key, index) => key === previousKeys[index] && current[key] === previous[key]
509
+ );
510
+ }
511
+ async function validateSkillSource(skillPath) {
512
+ await Promise.all(
513
+ REQUIRED_FILES.map(async (file) => {
514
+ if (!await pathExists(path3.join(skillPath, file))) {
515
+ throw new Error(`Invalid dypt toolkit source. Missing ${file}.`);
516
+ }
517
+ })
518
+ );
519
+ }
520
+ function githubApiUrl(pathname) {
521
+ return `https://api.github.com/repos/${TOOLKIT_REPO}${pathname}`;
522
+ }
523
+ async function fetchJson(url, fetchFn) {
524
+ const response = await fetchFn(url, {
525
+ headers: { Accept: "application/vnd.github+json" }
526
+ });
527
+ if (!response.ok) {
528
+ throw new Error(`Failed to fetch ${url}: ${response.status}`);
529
+ }
530
+ return await response.json();
531
+ }
532
+ async function downloadGitHubSource(source, fetchFn) {
533
+ const ref = source.type === "github-main" ? "main" : source.version ?? (await fetchJson(
534
+ githubApiUrl("/releases/latest"),
535
+ fetchFn
536
+ )).tag_name;
537
+ const tempRoot = await mkdtemp(path3.join(os2.tmpdir(), "dypt-toolkit-"));
538
+ const tree = await fetchJson(githubApiUrl(`/git/trees/${encodeURIComponent(ref)}?recursive=1`), fetchFn);
539
+ const skillFiles = tree.tree.filter(
540
+ (item) => item.type === "blob" && item.path.startsWith("skills/dypt-cli/")
541
+ );
542
+ await Promise.all(
543
+ skillFiles.map(async (item) => {
544
+ const targetPath = path3.join(tempRoot, item.path);
545
+ await mkdir2(path3.dirname(targetPath), { recursive: true });
546
+ const rawUrl = `https://raw.githubusercontent.com/${TOOLKIT_REPO}/${encodeURIComponent(ref)}/${item.path}`;
547
+ const response = await fetchFn(rawUrl);
548
+ if (!response.ok) {
549
+ throw new Error(`Failed to fetch ${item.path}: ${response.status}`);
550
+ }
551
+ await writeFile2(targetPath, await response.text());
552
+ })
553
+ );
554
+ return {
555
+ cleanup: () => rm2(tempRoot, { recursive: true, force: true }),
556
+ ref,
557
+ root: tempRoot,
558
+ skillPath: path3.join(tempRoot, SKILL_RELATIVE_PATH)
559
+ };
560
+ }
561
+ async function resolveSource(source, fetchFn) {
562
+ if (source.type === "local") {
563
+ const skillPath = path3.join(source.path, SKILL_RELATIVE_PATH);
564
+ await validateSkillSource(skillPath);
565
+ return {
566
+ cleanup: async () => void 0,
567
+ ref: "local",
568
+ root: source.path,
569
+ skillPath
570
+ };
571
+ }
572
+ const downloaded = await downloadGitHubSource(source, fetchFn);
573
+ await validateSkillSource(downloaded.skillPath);
574
+ return downloaded;
575
+ }
576
+ function getSourceLabel(source) {
577
+ if (source.type === "local") return "local";
578
+ if (source.type === "github-main") return "github-main";
579
+ return "github-release";
580
+ }
581
+ function resolveAgentSkillPath(target, options = {}) {
582
+ const env = options.env ?? process.env;
583
+ const homeDir = options.homeDir ?? os2.homedir();
584
+ if (target === "codex") {
585
+ return path3.join(env.CODEX_HOME ?? path3.join(homeDir, ".codex"), "skills", "dypt-cli");
586
+ }
587
+ return path3.join(homeDir, ".claude", "skills", "dypt-cli");
588
+ }
589
+ async function installAgentSkill(input) {
590
+ const fetchFn = input.fetch ?? fetch;
591
+ const targetPath = resolveAgentSkillPath(input.target, {
592
+ env: input.env,
593
+ homeDir: input.homeDir
594
+ });
595
+ const source = await resolveSource(input.source, fetchFn);
596
+ try {
597
+ const exists = await pathExists(targetPath);
598
+ const action = exists ? "update" : "install";
599
+ const metadata = exists ? await readMetadata(targetPath) : null;
600
+ if (exists && !input.force && !input.backup) {
601
+ if (!metadata) {
602
+ throw new Error(
603
+ "Installed dypt-cli skill is unmanaged. Use --backup or --force to replace it."
604
+ );
605
+ }
606
+ const currentHashes = await hashManagedFiles(targetPath);
607
+ if (!hashesMatch(currentHashes, metadata.files)) {
608
+ throw new Error(
609
+ "Installed dypt-cli skill has local modifications. Use --backup or --force to replace it."
610
+ );
611
+ }
612
+ }
613
+ const incomingHashes = await hashManagedFiles(source.skillPath);
614
+ const backupPath = exists && input.backup ? `${targetPath}.backup-${(input.now ?? /* @__PURE__ */ new Date()).toISOString().replaceAll(/[-:]/g, "").replace(".000", "")}` : void 0;
615
+ if (!input.dryRun) {
616
+ if (backupPath) {
617
+ await cp(targetPath, backupPath, { recursive: true });
618
+ }
619
+ await rm2(targetPath, { recursive: true, force: true });
620
+ await mkdir2(path3.dirname(targetPath), { recursive: true });
621
+ await cp(source.skillPath, targetPath, { recursive: true });
622
+ const installMetadata = {
623
+ source: getSourceLabel(input.source),
624
+ repo: TOOLKIT_REPO,
625
+ version: source.ref,
626
+ installedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
627
+ files: incomingHashes
628
+ };
629
+ await writeFile2(metadataPath(targetPath), `${JSON.stringify(installMetadata, null, 2)}
630
+ `);
631
+ }
632
+ return {
633
+ action,
634
+ backupPath,
635
+ dryRun: Boolean(input.dryRun),
636
+ path: targetPath,
637
+ target: input.target,
638
+ version: source.ref
639
+ };
640
+ } finally {
641
+ await source.cleanup();
642
+ }
643
+ }
644
+ async function appendAgentInstructions(input) {
645
+ const existing = await pathExists(input.filePath) ? await readFile2(input.filePath, "utf8") : "";
646
+ if (!input.force && existing.includes("## Work Tracking with dypt")) {
647
+ throw new Error(
648
+ `${input.filePath} already contains a dypt work-tracking section. Use --force to append anyway.`
649
+ );
650
+ }
651
+ if (!input.dryRun) {
652
+ await mkdir2(path3.dirname(input.filePath), { recursive: true });
653
+ const separator = existing.endsWith("\n") || existing.length === 0 ? "\n" : "\n\n";
654
+ await writeFile2(input.filePath, `${existing}${separator}${input.snippet}`);
655
+ }
656
+ return {
657
+ action: "append",
658
+ dryRun: Boolean(input.dryRun),
659
+ filePath: input.filePath
660
+ };
661
+ }
662
+ async function latestGitHubRelease(fetchFn) {
663
+ return (await fetchJson(
664
+ githubApiUrl("/releases/latest"),
665
+ fetchFn
666
+ )).tag_name;
667
+ }
668
+ async function getAgentStatus(input) {
669
+ const fetchFn = input.fetch ?? fetch;
670
+ const targets = await Promise.all(
671
+ ["codex", "claude"].map(async (target) => {
672
+ const targetPath = resolveAgentSkillPath(target, input);
673
+ const installed = await pathExists(targetPath);
674
+ const metadata = installed ? await readMetadata(targetPath) : null;
675
+ const modified = installed && metadata ? !hashesMatch(await hashManagedFiles(targetPath), metadata.files) : installed;
676
+ return {
677
+ target,
678
+ path: targetPath,
679
+ installed,
680
+ version: metadata?.version,
681
+ modified
682
+ };
683
+ })
684
+ );
685
+ let latestVersion;
686
+ try {
687
+ latestVersion = await latestGitHubRelease(fetchFn);
688
+ } catch {
689
+ latestVersion = void 0;
690
+ }
691
+ return {
692
+ latestVersion,
693
+ targets: targets.map((target) => ({
694
+ ...target,
695
+ updateAvailable: Boolean(latestVersion && target.version && latestVersion !== target.version)
696
+ }))
697
+ };
698
+ }
699
+
700
+ // src/commands/agent/install.ts
701
+ function resolveSource2(input) {
702
+ if (input.source === "local") {
703
+ if (!input.path) {
704
+ throw new Error("Use --path <local-toolkit-path> with --source local.");
705
+ }
706
+ return { type: "local", path: input.path };
707
+ }
708
+ if (input.source === "github-main") {
709
+ return { type: "github-main" };
710
+ }
711
+ return {
712
+ type: "github-release",
713
+ version: input.version
714
+ };
715
+ }
716
+ async function runAgentInstall(input, deps) {
717
+ const result = await installAgentSkill({
718
+ target: input.target,
719
+ source: resolveSource2(input),
720
+ dryRun: input.dryRun,
721
+ yes: input.yes,
722
+ force: input.force,
723
+ backup: input.backup,
724
+ isTty: deps.isTty
725
+ });
726
+ if (input.json) {
727
+ deps.printJson(result);
728
+ return;
729
+ }
730
+ deps.printTable(result);
731
+ }
732
+
733
+ // src/commands/agent/installInstructions.ts
734
+ async function runAgentInstallInstructions(input, deps) {
735
+ const result = input.append ? await appendAgentInstructions({
736
+ filePath: input.append,
737
+ snippet: AGENT_INSTRUCTIONS_SNIPPET,
738
+ dryRun: input.dryRun,
739
+ force: input.force
740
+ }) : {
741
+ snippet: AGENT_INSTRUCTIONS_SNIPPET,
742
+ appendHint: AGENT_INSTRUCTIONS_APPEND_HINT
743
+ };
744
+ if (input.json) {
745
+ deps.printJson(result);
746
+ return;
747
+ }
748
+ deps.printTable(result);
749
+ }
750
+
751
+ // src/commands/agent/status.ts
752
+ async function runAgentStatus(input, deps) {
753
+ const result = await deps.getStatus();
754
+ if (input.json) {
755
+ deps.printJson(result);
756
+ return;
757
+ }
758
+ deps.printTable(result);
759
+ }
760
+
384
761
  // src/commands/auth/status.ts
385
762
  async function runStatus(input, deps) {
386
763
  const result = await deps.getStatus();
@@ -726,7 +1103,7 @@ async function runTaskUpdateMany(input, deps) {
726
1103
  }
727
1104
 
728
1105
  // src/commands/task/cleanupPlan.ts
729
- import { readFile as readFile2 } from "fs/promises";
1106
+ import { readFile as readFile3 } from "fs/promises";
730
1107
  async function loadCleanupPlan(input) {
731
1108
  if (input.plan && input.planFile) {
732
1109
  throw new Error("Use either --plan or --plan-file, not both.");
@@ -734,7 +1111,7 @@ async function loadCleanupPlan(input) {
734
1111
  if (!input.plan && !input.planFile) {
735
1112
  throw new Error("Provide a cleanup plan with --plan or --plan-file.");
736
1113
  }
737
- const raw = input.plan ?? await readFile2(input.planFile, "utf8");
1114
+ const raw = input.plan ?? await readFile3(input.planFile, "utf8");
738
1115
  try {
739
1116
  return JSON.parse(raw);
740
1117
  } catch {
@@ -1017,6 +1394,17 @@ function isTaskCollection(value) {
1017
1394
  function isAuthStatusLike(value) {
1018
1395
  return isRecord(value) && isRecord(value.user) && typeof value.user.userId === "string" && isRecord(value.token) && typeof value.token.id === "number" && typeof value.token.label === "string" && typeof value.token.scope === "string";
1019
1396
  }
1397
+ function isAgentInstallResultLike(value) {
1398
+ return isRecord(value) && typeof value.target === "string" && (value.action === "install" || value.action === "update") && typeof value.path === "string";
1399
+ }
1400
+ function isAgentInstructionsLike(value) {
1401
+ return isRecord(value) && (typeof value.snippet === "string" || value.action === "append");
1402
+ }
1403
+ function isAgentStatusLike(value) {
1404
+ return isRecord(value) && Array.isArray(value.targets) && value.targets.every(
1405
+ (target) => isRecord(target) && typeof target.target === "string" && typeof target.path === "string" && typeof target.installed === "boolean"
1406
+ );
1407
+ }
1020
1408
  function isTaskDetailLike(value) {
1021
1409
  return isRecord(value) && isTaskLike(value.task) && (value.taskChildren === void 0 || Array.isArray(value.taskChildren) && value.taskChildren.every(isTaskLike)) && (value.taskParents === void 0 || Array.isArray(value.taskParents) && value.taskParents.every(isTaskLike));
1022
1410
  }
@@ -1703,6 +2091,52 @@ function renderAuthStatus(result, color) {
1703
2091
  `Last used: ${formatDateTimeValue(result.token.lastUsedAt)}`
1704
2092
  ].join("\n");
1705
2093
  }
2094
+ function renderAgentInstallResult(result, color) {
2095
+ const verb = result.action === "install" ? result.dryRun ? "Would install" : "Installed" : result.dryRun ? "Would update" : "Updated";
2096
+ const lines = [
2097
+ `${colorize(verb, result.dryRun ? "yellow" : "green", color)} dypt agent guidance for ${result.target}`,
2098
+ `Path: ${result.path}`
2099
+ ];
2100
+ if (result.version) {
2101
+ lines.push(`Version: ${result.version}`);
2102
+ }
2103
+ if (result.backupPath) {
2104
+ lines.push(`Backup: ${result.backupPath}`);
2105
+ }
2106
+ return lines.join("\n");
2107
+ }
2108
+ function renderAgentInstructions(result, color) {
2109
+ if (typeof result.snippet === "string") {
2110
+ const lines = [result.snippet.trimEnd()];
2111
+ if (result.appendHint) {
2112
+ lines.push("", dim(result.appendHint, color));
2113
+ }
2114
+ return lines.join("\n");
2115
+ }
2116
+ if (result.action === "append" && result.filePath) {
2117
+ const verb = result.dryRun ? "Would append" : "Appended";
2118
+ return `${colorize(verb, result.dryRun ? "yellow" : "green", color)} dypt instructions to ${result.filePath}`;
2119
+ }
2120
+ return JSON.stringify(result, null, 2);
2121
+ }
2122
+ function renderAgentStatus(result, color) {
2123
+ const lines = [
2124
+ "dypt agent guidance status",
2125
+ `Latest release: ${result.latestVersion ?? "-"}`,
2126
+ "",
2127
+ ...result.targets.map((target) => {
2128
+ const status = target.installed ? target.modified ? colorize("modified", "yellow", color) : colorize("installed", "green", color) : dim("not installed", color);
2129
+ const update = target.updateAvailable === true ? colorize("update available", "yellow", color) : "up to date";
2130
+ return [
2131
+ `${target.target}: ${status}`,
2132
+ ` Path: ${target.path}`,
2133
+ ` Version: ${target.version ?? "-"}`,
2134
+ ` Update: ${target.installed ? update : "-"}`
2135
+ ].join("\n");
2136
+ })
2137
+ ];
2138
+ return lines.join("\n");
2139
+ }
1706
2140
  function formatHumanOutput(value, options = {}) {
1707
2141
  const color = options.color ?? Boolean(process.stdout.isTTY);
1708
2142
  if (Array.isArray(value) && value.length === 0) {
@@ -1732,6 +2166,15 @@ function formatHumanOutput(value, options = {}) {
1732
2166
  if (isAuthStatusLike(value)) {
1733
2167
  return renderAuthStatus(value, color);
1734
2168
  }
2169
+ if (isAgentInstallResultLike(value)) {
2170
+ return renderAgentInstallResult(value, color);
2171
+ }
2172
+ if (isAgentInstructionsLike(value)) {
2173
+ return renderAgentInstructions(value, color);
2174
+ }
2175
+ if (isAgentStatusLike(value)) {
2176
+ return renderAgentStatus(value, color);
2177
+ }
1735
2178
  if (isDependencyCollection(value)) {
1736
2179
  return renderDependencies(value, color);
1737
2180
  }
@@ -1796,6 +2239,8 @@ var taskStatusChoices = [
1796
2239
  "completed"
1797
2240
  ];
1798
2241
  var taskPriorityChoices = ["low", "mid", "medium", "high"];
2242
+ var agentTargetChoices = ["codex", "claude"];
2243
+ var agentSourceChoices = ["github-release", "github-main", "local"];
1799
2244
  function normalizePriority(priority) {
1800
2245
  if (!priority) return void 0;
1801
2246
  if (priority === "medium") return "mid";
@@ -1870,8 +2315,8 @@ function resolveTaskRefFromSearchMatches(ref, matches) {
1870
2315
  }
1871
2316
  if (exactMatches.length > 1) {
1872
2317
  const formattedMatches = exactMatches.map((task) => {
1873
- const path3 = task.pathTitles?.join(" > ") ?? (task.parentTitle ? `${task.parentTitle} > ${task.title}` : task.title);
1874
- return `- #${task.id} ${path3}`;
2318
+ const path4 = task.pathTitles?.join(" > ") ?? (task.parentTitle ? `${task.parentTitle} > ${task.title}` : task.title);
2319
+ return `- #${task.id} ${path4}`;
1875
2320
  }).join("\n");
1876
2321
  throw new Error(`Task reference is ambiguous: ${ref}
1877
2322
  ${formattedMatches}`);
@@ -1948,6 +2393,67 @@ function buildCli() {
1948
2393
  auth.command("logout").description("Remove the local CLI token").action(async () => {
1949
2394
  await runLogout(createDefaultLogoutDeps());
1950
2395
  });
2396
+ const agent = addGroupHelpAction(
2397
+ program.command("agent").description("Agent guidance commands")
2398
+ );
2399
+ agent.command("install").description("Install or update dypt agent guidance").addArgument(
2400
+ new Argument(
2401
+ "<target>",
2402
+ `agent target (${agentTargetChoices.join("|")})`
2403
+ ).choices([...agentTargetChoices])
2404
+ ).addOption(
2405
+ new Option(
2406
+ "--source <source>",
2407
+ `toolkit source (${agentSourceChoices.join("|")})`
2408
+ ).choices([...agentSourceChoices]).default("github-release")
2409
+ ).option("--version <tag>", "GitHub release tag to install").option("--path <local-toolkit-path>", "local dypt-toolkit path").option("--dry-run", "show planned install without writing files").option("--yes", "approve safe prompts").option("--force", "replace modified or unmanaged installs").option("--backup", "back up an existing install before replacing it").option("--json", "print JSON output").action(
2410
+ async (target, options) => {
2411
+ await runAgentInstall(
2412
+ {
2413
+ target,
2414
+ source: options.source,
2415
+ version: options.version,
2416
+ path: options.path,
2417
+ dryRun: Boolean(options.dryRun),
2418
+ yes: Boolean(options.yes),
2419
+ force: Boolean(options.force),
2420
+ backup: Boolean(options.backup),
2421
+ json: Boolean(options.json)
2422
+ },
2423
+ {
2424
+ isTty: Boolean(process.stdout.isTTY),
2425
+ printJson,
2426
+ printTable
2427
+ }
2428
+ );
2429
+ }
2430
+ );
2431
+ agent.command("status").description("Show dypt agent guidance install status").option("--json", "print JSON output").action(async (options) => {
2432
+ await runAgentStatus(
2433
+ { json: Boolean(options.json) },
2434
+ {
2435
+ getStatus: () => getAgentStatus({}),
2436
+ printJson,
2437
+ printTable
2438
+ }
2439
+ );
2440
+ });
2441
+ agent.command("install-instructions").description("Print or append repo-level dypt agent instructions").option("--append <file>", "append instructions to the given file").option("--dry-run", "show planned change without writing files").option("--force", "append even if a dypt section already exists").option("--yes", "approve safe prompts").option("--json", "print JSON output").action(
2442
+ async (options) => {
2443
+ await runAgentInstallInstructions(
2444
+ {
2445
+ append: options.append,
2446
+ dryRun: Boolean(options.dryRun),
2447
+ force: Boolean(options.force),
2448
+ json: Boolean(options.json)
2449
+ },
2450
+ {
2451
+ printJson,
2452
+ printTable
2453
+ }
2454
+ );
2455
+ }
2456
+ );
1951
2457
  const task = addGroupHelpAction(
1952
2458
  program.command("task").description("Task commands")
1953
2459
  );