@nalvietnam/avatar-cli 1.7.1 → 1.9.0

package/dist/index.js

@@ -1297,6 +1297,11 @@ async function checkoutTagInSubmodule(submodulePath, tag, cwd = process.cwd()) {
   await git(submoduleCwd).fetch(["--tags"]);
   await git(submoduleCwd).checkout(tag);
 }
+async function checkoutBranchHeadInSubmodule(submodulePath, branch, cwd = process.cwd()) {
+  const submoduleCwd = join8(cwd, submodulePath);
+  await git(submoduleCwd).fetch(["origin"]);
+  await git(submoduleCwd).checkout(["-B", branch, `origin/${branch}`]);
+}
 async function listTags(cwd = process.cwd()) {
   const result = await git(cwd).tags();
   return result.all;
@@ -2308,7 +2313,7 @@ function registerGitnexusCommand(program2) {
 // src/commands/init.ts
 import { basename, join as join24, relative as relative3, resolve } from "path";
 import { confirm as confirm5, input as input5, select as select9 } from "@inquirer/prompts";
-import boxen5 from "boxen";
+import boxen6 from "boxen";
 
 // src/lib/add-team-pack-submodule-with-retry-on-network-fail.ts
 import { spawnSync as spawnSync13 } from "child_process";
@@ -3196,6 +3201,42 @@ function linkExistingRemoteToWorkspace(args) {
   return { sshUrl, httpsUrl };
 }
 
+// src/lib/format-pack-commands-cheatsheet-box.ts
+import boxen4 from "boxen";
+var PACK_COMMAND_CHEATSHEET = [
+  { cmd: "/avatar:help", desc: "H\u01B0\u1EDBng d\u1EABn s\u1EED d\u1EE5ng Avatar \u2014 ch\u1EC9 c\u1EA7n g\xF5 t\u1EF1 nhi\xEAn" },
+  { cmd: "/avatar:brainstorm", desc: "Brainstorm \xFD t\u01B0\u1EDFng cho m\u1ED9t feature" },
+  { cmd: "/avatar:plan", desc: "T\u1EA1o plan th\xF4ng minh v\u1EDBi prompt enhancement" },
+  { cmd: "/avatar:scout", desc: "T\xECm file li\xEAn quan trong codebase, ti\u1EBFt ki\u1EC7m token" },
+  { cmd: "/avatar:implement", desc: "B\u1EAFt \u0111\u1EA7u code & test theo plan c\xF3 s\u1EB5n" },
+  { cmd: "/avatar:build-full-flow", desc: "Implement m\u1ED9t feature t\u1EEBng b\u01B0\u1EDBc (end-to-end)" },
+  { cmd: "/avatar:fix", desc: "Ph\xE2n t\xEDch v\xE0 fix v\u1EA5n \u0111\u1EC1 t\u1EF1 \u0111i\u1EC1u h\u01B0\u1EDBng" },
+  { cmd: "/avatar:debug", desc: "Debug v\u1EA5n \u0111\u1EC1 k\u1EF9 thu\u1EADt + \u0111\u01B0a ra gi\u1EA3i ph\xE1p" },
+  { cmd: "/avatar:test", desc: "Ch\u1EA1y test tr\xEAn m\xE1y + ph\xE2n t\xEDch b\xE1o c\xE1o t\u1ED5ng h\u1EE3p" },
+  { cmd: "/avatar:design:good", desc: "T\u1EA1o thi\u1EBFt k\u1EBF ch\u1EC9n chu, s\u1ED1ng \u0111\u1ED9ng" },
+  { cmd: "/avatar:docs:init", desc: "Ph\xE2n t\xEDch codebase + t\u1EA1o t\xE0i li\u1EC7u kh\u1EDFi \u0111\u1EA7u" },
+  { cmd: "/avatar:status", desc: "Xem l\u1EA1i thay \u0111\u1ED5i g\u1EA7n \u0111\xE2y + t\u1ED5ng k\u1EBFt c\xF4ng vi\u1EC7c" },
+  { cmd: "/avatar:journal", desc: "Ghi nh\u1EADt k\xFD session" }
+];
+function formatPackCommandsCheatsheetBox() {
+  const maxCmdWidth = Math.max(...PACK_COMMAND_CHEATSHEET.map((e) => e.cmd.length));
+  const header = chalk.bold("\u{1F3AF} Slash commands t\u1EEB team-ai-pack");
+  const subheader = chalk.dim("G\xF5 trong Claude Code session \u0111\u1EC3 g\u1ECDi capability c\u1EE7a pack:");
+  const lines = PACK_COMMAND_CHEATSHEET.map((e) => {
+    const cmdPadded = chalk.cyan(e.cmd.padEnd(maxCmdWidth));
+    return `  ${cmdPadded}  ${chalk.dim(e.desc)}`;
+  });
+  const footer = chalk.dim(
+    "Catalog \u0111\u1EA7y \u0111\u1EE7 46 commands: cat .claude/pack/scripts/commands_data.yaml"
+  );
+  const content = [header, subheader, "", ...lines, "", footer].join("\n");
+  return boxen4(content, {
+    padding: 1,
+    borderStyle: "round",
+    borderColor: "cyan"
+  });
+}
+
 // src/lib/merge-pack-settings-into-project-settings.ts
 import { promises as fs9 } from "fs";
 import { join as join17 } from "path";
@@ -3756,7 +3797,7 @@ function buildScaffoldVariables(args) {
 }
 
 // src/commands/login.ts
-import boxen4 from "boxen";
+import boxen5 from "boxen";
 import open from "open";
 
 // src/lib/google-oauth-device-flow.ts
@@ -3903,7 +3944,7 @@ async function runLogin(opts) {
     "",
     `Ho\u1EB7c Avatar t\u1EF1 m\u1EDF browser, click ${chalk.green("Allow")}...`
   ].join("\n");
-  process.stdout.write(`${boxen4(instructions, { padding: 1, borderStyle: "round" })}
+  process.stdout.write(`${boxen5(instructions, { padding: 1, borderStyle: "round" })}
 `);
   void open(verificationUrl).catch(() => {
     log.dim("(Kh\xF4ng m\u1EDF \u0111\u01B0\u1EE3c browser t\u1EF1 \u0111\u1ED9ng \u2014 copy URL \u1EDF tr\xEAn)");
@@ -4300,7 +4341,7 @@ async function finalizeWorkspaceScaffold(args) {
     await writeRootClaudeMd(args.workspacePath, updatedVars);
     log.dim("Updated CLAUDE.md v\u1EDBi GitNexus section");
   }
-  printInitSuccessBox(args.workspacePath, args.flow, aiResult, gitnexusResult);
+  await printInitSuccessBox(args.workspacePath, args.flow, aiResult, gitnexusResult);
 }
 async function autoSyncPackOnInit(workspacePath) {
   const packDir = join24(workspacePath, TEAM_PACK_RELATIVE_PATH);
@@ -4494,7 +4535,7 @@ function formatGitnexusStatusLine(result) {
   }
   return `  ${chalk.yellow("GitNexus:")} skipped (${(result.reason ?? "unknown").slice(0, 40)}) \xB7 th\u1EED ${chalk.cyan("avatar gitnexus install")}`;
 }
-function printInitSuccessBox(rootPath, flow, aiResult = null, gitnexusResult = null) {
+async function printInitSuccessBox(rootPath, flow, aiResult = null, gitnexusResult = null) {
   const lines = [
     `${chalk.green("\u2713")} Workspace s\u1EB5n s\xE0ng: ${relative3(process.cwd(), rootPath) || rootPath}`,
     `  ${chalk.dim(`(flow: ${flow})`)}`,
@@ -4508,8 +4549,14 @@ function printInitSuccessBox(rootPath, flow, aiResult = null, gitnexusResult = n
     `  ${chalk.cyan("avatar sync")}               Pull team-ai-pack m\u1EDBi`,
     `  ${chalk.cyan("avatar uninstall")}          G\u1EE1 Avatar (gi\u1EEF code)`
   ];
-  process.stdout.write(`${boxen5(lines.join("\n"), { padding: 1, borderStyle: "round" })}
+  process.stdout.write(`${boxen6(lines.join("\n"), { padding: 1, borderStyle: "round" })}
 `);
+  const packDir = join24(rootPath, TEAM_PACK_RELATIVE_PATH);
+  if (await pathExists(packDir)) {
+    process.stdout.write(`
+${formatPackCommandsCheatsheetBox()}
+`);
+  }
 }
 
 // src/lib/not-implemented-stub.ts
@@ -4561,7 +4608,7 @@ function registerSecretsCommand(program2) {
 // src/commands/status.ts
 import { promises as fs13 } from "fs";
 import { join as join26 } from "path";
-import boxen6 from "boxen";
+import boxen7 from "boxen";
 
 // src/lib/pack-backup-manager.ts
 import { promises as fs12 } from "fs";
@@ -4639,7 +4686,7 @@ function renderStatusBox(s) {
     `${chalk.dim("Backups:")}            ${s.backupCount}`,
     `${chalk.dim("Tech stack:")}         ${s.techStackSummary}`
   ];
-  process.stdout.write(`${boxen6(lines.join("\n"), { padding: 1, borderStyle: "round" })}
+  process.stdout.write(`${boxen7(lines.join("\n"), { padding: 1, borderStyle: "round" })}
 `);
 }
 
@@ -4689,6 +4736,7 @@ async function buildSyncPreview(packDir, claudeDir, targetVersion) {
 }
 
 // src/commands/sync.ts
+var DEFAULT_PACK_BRANCH = "main";
 async function syncAction(opts) {
   const projectRoot = process.cwd();
   const claudeDir = join28(projectRoot, ".claude");
@@ -4708,16 +4756,23 @@ async function syncAction(opts) {
       `Kh\xF4ng fetch \u0111\u01B0\u1EE3c tags t\u1EEB origin (${err instanceof Error ? err.message : err}). S\u1EBD d\xF9ng tag local hi\u1EC7n c\xF3.`
     );
   }
+  const useLatestMode = opts.latest === true && !opts.version;
   const allTags = await listTags(packDir);
-  const targetVersion = opts.version ?? pickLatestStableSemVerTag(allTags);
-  if (!targetVersion) {
-    log.error(
-      `Kh\xF4ng t\xECm th\u1EA5y stable SemVer tag (vMAJOR.MINOR.PATCH) trong team-ai-pack submodule.
+  let targetVersion;
+  if (useLatestMode) {
+    targetVersion = `${DEFAULT_PACK_BRANCH} (HEAD)`;
+  } else {
+    const picked = opts.version ?? pickLatestStableSemVerTag(allTags);
+    if (!picked) {
+      log.error(
+        `Kh\xF4ng t\xECm th\u1EA5y stable SemVer tag (vMAJOR.MINOR.PATCH) trong team-ai-pack submodule.
   Tags hi\u1EC7n c\xF3: ${allTags.length > 0 ? allTags.join(", ") : "(none)"}
-  Pass --version <tag> r\xF5 r\xE0ng, ho\u1EB7c tag pack theo SemVer convention.`
-    );
-    process.exit(1);
-    return;
+  Pass --version <tag> r\xF5 r\xE0ng, ho\u1EB7c d\xF9ng --latest \u0111\u1EC3 pull HEAD branch ${DEFAULT_PACK_BRANCH}.`
+      );
+      process.exit(1);
+      return;
+    }
+    targetVersion = picked;
   }
   if (opts.dryRun) {
     const preview = await buildSyncPreview(packDir, claudeDir, targetVersion);
@@ -4741,8 +4796,18 @@ async function syncAction(opts) {
     log.info("\nDry-run done. Kh\xF4ng apply thay \u0111\u1ED5i. B\u1ECF --dry-run \u0111\u1EC3 th\u1EF1c thi.");
     return;
   }
-  log.info(`Checking out ${targetVersion} trong submodule...`);
-  await checkoutTagInSubmodule(TEAM_PACK_RELATIVE_PATH, targetVersion, projectRoot);
+  if (useLatestMode) {
+    log.info(`Pulling HEAD c\u1EE7a branch ${DEFAULT_PACK_BRANCH} (bleeding-edge mode)...`);
+    await checkoutBranchHeadInSubmodule(TEAM_PACK_RELATIVE_PATH, DEFAULT_PACK_BRANCH, projectRoot);
+    const sha = await currentCommitSha(packDir);
+    log.dim(`  HEAD = ${sha.slice(0, 7)}`);
+    log.warn(
+      "\u26A0 --latest mode: workspace pin v\xE0o commit floating, kh\xF4ng reproducible. Chuy\u1EC3n v\u1EC1 tag stable: avatar sync (no flag)."
+    );
+  } else {
+    log.info(`Checking out ${targetVersion} trong submodule...`);
+    await checkoutTagInSubmodule(TEAM_PACK_RELATIVE_PATH, targetVersion, projectRoot);
+  }
   log.info("Creating symlink farm...");
   const results = await syncAllMountDirs(packDir, claudeDir, opts.force === true);
   reportResults(results, opts.force === true);
@@ -4799,7 +4864,7 @@ function reportResults(results, force) {
   }
 }
 function registerSyncCommand(program2) {
-  program2.command("sync").description("Pull team-ai-pack m\u1EDBi nh\u1EA5t + t\u1EA1o symlink farm v\xE0o .claude/").option("--force", "Override .claude/<dir>/ n\u1EBFu l\xE0 real dir (backup tr\u01B0\u1EDBc)").option("--version <tag>", "Pin v\xE0o version c\u1EE5 th\u1EC3 (vd: v0.2.0)").option("--dry-run", "Hi\u1EC3n th\u1ECB preview, kh\xF4ng apply thay \u0111\u1ED5i").action(syncAction);
+  program2.command("sync").description("Pull team-ai-pack m\u1EDBi nh\u1EA5t + t\u1EA1o symlink farm v\xE0o .claude/").option("--force", "Override .claude/<dir>/ n\u1EBFu l\xE0 real dir (backup tr\u01B0\u1EDBc)").option("--version <tag>", "Pin v\xE0o version c\u1EE5 th\u1EC3 (vd: v0.2.0)").option("--latest", "Bleeding-edge: pull HEAD c\u1EE7a main branch (b\u1ECF qua tag SemVer)").option("--dry-run", "Hi\u1EC3n th\u1ECB preview, kh\xF4ng apply thay \u0111\u1ED5i").action(syncAction);
 }
 
 // src/commands/tools.ts
@@ -4813,7 +4878,7 @@ function registerToolsCommand(program2) {
 // src/commands/uninstall.ts
 import { relative as relative4 } from "path";
 import { confirm as confirm6 } from "@inquirer/prompts";
-import boxen7 from "boxen";
+import boxen8 from "boxen";
 
 // src/lib/create-uninstall-backup-snapshot.ts
 import { cp, mkdir, writeFile } from "fs/promises";
@@ -4967,7 +5032,7 @@ async function removeSubmoduleEntry(gitmodulesPath, submodulePath) {
 }
 
 // src/commands/uninstall.ts
-var CLI_VERSION = "1.7.1";
+var CLI_VERSION = "1.9.0";
 function registerUninstallCommand(program2) {
   program2.command("uninstall").description("G\u1EE1 Avatar kh\u1ECFi project \u2014 backup t\u1EF1 \u0111\u1ED9ng (M11)").option("--yes", "Skip confirm prompt").option("--no-backup", "Kh\xF4ng t\u1EA1o backup tr\u01B0\u1EDBc khi x\xF3a (nguy hi\u1EC3m)").option("--keep-submodule", "Gi\u1EEF submodule .claude/pack/").option("--keep-hooks", "Gi\u1EEF git hooks post-merge, pre-push").option("--dry-run", "Hi\u1EC3n th\u1ECB danh s\xE1ch s\u1EBD x\xF3a, kh\xF4ng th\u1EF1c thi").action(async (opts) => {
     try {
@@ -5044,12 +5109,12 @@ function printUninstallSuccessBox(backupPath) {
     lines.push(`  ${chalk.dim("Backup:")} ${backupPath}`);
     lines.push(`  ${chalk.dim("Restore:")} ${chalk.cyan(`cp -r "${backupPath}"/* .`)}`);
   }
-  process.stdout.write(`${boxen7(lines.join("\n"), { padding: 1, borderStyle: "round" })}
+  process.stdout.write(`${boxen8(lines.join("\n"), { padding: 1, borderStyle: "round" })}
 `);
 }
 
 // src/index.ts
-var CLI_VERSION2 = "1.7.1";
+var CLI_VERSION2 = "1.9.0";
 var program = new Command();
 program.name("avatar").description("AI harness CLI for NAL Vietnam engineering").version(CLI_VERSION2, "-v, --version", "Hi\u1EC3n th\u1ECB phi\xEAn b\u1EA3n Avatar CLI").addHelpText(
   "beforeAll",