@take-out/cli 0.7.0-1784497775575 → 0.7.0

package/README.md

@@ -63,8 +63,7 @@ takeout check
 
 #### `takeout docs`
 
-Read documentation from the current repository's `skills/` or `docs/`
-directory:
+Manage and retrieve documentation files:
 
 ```bash
 # list available docs
@@ -76,6 +75,9 @@ takeout docs get zero tamagui
 # get path to docs directory
 takeout docs path
 
+# eject docs to local ./docs folder
+takeout docs eject
+
 # generate Claude Code skills from docs
 takeout skills generate
 takeout skills generate --clean  # clean and regenerate
@@ -85,7 +87,7 @@ takeout skills generate --clean  # clean and regenerate
 
 The `skills generate` command generates Claude Code skills from your documentation:
 
-1. scans docs from `./skills/` when present, otherwise `./docs/`
+1. scans docs from both `./docs/` (local) and package docs
 2. only docs with YAML frontmatter containing `name` and `description` become skills
 3. those docs are symlinked into `.claude/skills/`
 

package/dist/cjs/commands/docs.cjs

@@ -37,39 +37,45 @@ __export(docs_exports, {
 });
 module.exports = __toCommonJS(docs_exports);
 var import_node_fs = require("node:fs");
+var import_node_module = require("node:module");
 var import_node_path = require("node:path");
 var import_citty = require("citty");
 var import_picocolors = __toESM(require("picocolors"), 1);
-function resolveDocsDir(cwd = process.cwd()) {
-  const skillsDir = (0, import_node_path.join)(cwd, "skills");
-  if ((0, import_node_fs.existsSync)(skillsDir)) return skillsDir;
-  const docsDir = (0, import_node_path.join)(cwd, "docs");
-  if ((0, import_node_fs.existsSync)(docsDir)) return docsDir;
-  throw new Error(`No docs or skills directory found in ${cwd}`);
-}
+var import_sync = require("../utils/sync.cjs");
+const import_meta = {};
+const require2 = (0, import_node_module.createRequire)(import_meta.url);
+const DOCS_DIR = (0, import_node_path.dirname)(require2.resolve("@take-out/docs/package.json"));
 const listCommand = (0, import_citty.defineCommand)({
   meta: {
     name: "list",
-    description: "List repository documentation files"
+    description: "List all available documentation files"
   },
   async run() {
-    let docsDir;
-    try {
-      docsDir = resolveDocsDir();
-    } catch (error) {
-      console.error(import_picocolors.default.red(`\u2717 ${error instanceof Error ? error.message : String(error)}`));
+    if (!(0, import_node_fs.existsSync)(DOCS_DIR)) {
+      console.error(import_picocolors.default.red("\u2717 Docs directory not found"));
       process.exit(1);
     }
-    const files = (0, import_node_fs.readdirSync)(docsDir).filter(file => file.endsWith(".md")).sort();
+    const files = (0, import_node_fs.readdirSync)(DOCS_DIR).filter(f => f.endsWith(".md")).sort();
     console.info();
     console.info(import_picocolors.default.bold(import_picocolors.default.cyan("\u{1F4DA} Available Documentation")));
     console.info();
     for (const file of files) {
       const name = file.replace(/\.md$/, "");
-      const content = (0, import_node_fs.readFileSync)((0, import_node_path.join)(docsDir, file), "utf-8");
-      const heading = content.match(/^#\s+(.+)$/m)?.[1];
-      console.info(`  ${import_picocolors.default.green(name)}`);
-      if (heading) console.info(`    ${import_picocolors.default.dim(heading)}`);
+      const path = (0, import_node_path.join)(DOCS_DIR, file);
+      let description = "";
+      try {
+        const content = (0, import_node_fs.readFileSync)(path, "utf-8");
+        const match = content.match(/^#\s+(.+)$/m);
+        if (match?.[1]) {
+          description = match[1];
+        }
+      } catch {}
+      if (description) {
+        console.info(`  ${import_picocolors.default.green(name)}`);
+        console.info(`    ${import_picocolors.default.dim(description)}`);
+      } else {
+        console.info(`  ${import_picocolors.default.green(name)}`);
+      }
     }
     console.info();
     console.info(import_picocolors.default.dim(`Use 'takeout docs get <name>' to view a document`));
@@ -79,7 +85,7 @@ const listCommand = (0, import_citty.defineCommand)({
 const getCommand = (0, import_citty.defineCommand)({
   meta: {
     name: "get",
-    description: "Get the content of one or more repository documentation files"
+    description: "Get the content of one or more documentation files"
   },
   args: {
     name: {
@@ -92,38 +98,65 @@ const getCommand = (0, import_citty.defineCommand)({
   async run({
     args
   }) {
-    let docsDir;
-    try {
-      docsDir = resolveDocsDir();
-    } catch (error) {
-      console.error(import_picocolors.default.red(`\u2717 ${error instanceof Error ? error.message : String(error)}`));
-      process.exit(1);
-    }
     const names = args._.length > 0 ? args._ : [args.name];
     const results = [];
+    const errors = [];
+    const cwd = process.cwd();
+    const localSkillsDir = (0, import_node_path.join)(cwd, "skills");
+    const localDocsDir = (0, import_node_path.join)(cwd, "docs");
     for (const name of names) {
       const fileName = name.endsWith(".md") ? name : `${name}.md`;
-      const filePath = (0, import_node_path.join)(docsDir, fileName);
-      if (!(0, import_node_fs.existsSync)(filePath)) {
-        console.error(import_picocolors.default.red(`\u2717 Doc file not found: ${name}`));
+      const localSkillsPath = (0, import_node_path.join)(localSkillsDir, fileName);
+      const localDocsPath = (0, import_node_path.join)(localDocsDir, fileName);
+      const packageFilePath = (0, import_node_path.join)(DOCS_DIR, fileName);
+      let filePath = null;
+      if ((0, import_node_fs.existsSync)(localSkillsPath)) {
+        filePath = localSkillsPath;
+      } else if ((0, import_node_fs.existsSync)(localDocsPath)) {
+        filePath = localDocsPath;
+      } else if ((0, import_node_fs.existsSync)(packageFilePath)) {
+        filePath = packageFilePath;
+      }
+      if (!filePath) {
+        errors.push({
+          name,
+          error: "File not found"
+        });
         continue;
       }
-      results.push({
-        name,
-        content: (0, import_node_fs.readFileSync)(filePath, "utf-8")
-      });
+      try {
+        const content = (0, import_node_fs.readFileSync)(filePath, "utf-8");
+        results.push({
+          name,
+          content
+        });
+      } catch (err) {
+        errors.push({
+          name,
+          error: String(err)
+        });
+      }
     }
-    if (results.length === 0) {
+    if (errors.length > 0) {
+      for (const {
+        name
+      } of errors) {
+        console.error(import_picocolors.default.red(`\u2717 Doc file not found: ${name}`));
+      }
       console.info();
       console.info(import_picocolors.default.dim(`Use 'takeout docs list' to see available docs`));
-      process.exit(1);
+      if (results.length === 0) {
+        process.exit(1);
+      }
+      console.info();
     }
-    for (let index = 0; index < results.length; index++) {
-      const result = results[index];
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      if (!result) continue;
       console.info(`# ${result.name}`);
       console.info();
       console.info(result.content);
-      if (index < results.length - 1) {
+      if (i < results.length - 1) {
         console.info();
         console.info("---");
         console.info();
@@ -134,7 +167,7 @@ const getCommand = (0, import_citty.defineCommand)({
 const pathCommand = (0, import_citty.defineCommand)({
   meta: {
     name: "path",
-    description: "Get the absolute path to repository documentation"
+    description: "Get the absolute path to a documentation file"
   },
   args: {
     name: {
@@ -146,19 +179,12 @@ const pathCommand = (0, import_citty.defineCommand)({
   async run({
     args
   }) {
-    let docsDir;
-    try {
-      docsDir = resolveDocsDir();
-    } catch (error) {
-      console.error(import_picocolors.default.red(`\u2717 ${error instanceof Error ? error.message : String(error)}`));
-      process.exit(1);
-    }
     if (!args.name) {
-      console.info(docsDir);
+      console.info(DOCS_DIR);
       return;
     }
     const fileName = args.name.endsWith(".md") ? args.name : `${args.name}.md`;
-    const filePath = (0, import_node_path.join)(docsDir, fileName);
+    const filePath = (0, import_node_path.join)(DOCS_DIR, fileName);
     if (!(0, import_node_fs.existsSync)(filePath)) {
       console.error(import_picocolors.default.red(`\u2717 Doc file not found: ${args.name}`));
       process.exit(1);
@@ -166,14 +192,114 @@ const pathCommand = (0, import_citty.defineCommand)({
     console.info(filePath);
   }
 });
+const ejectCommand = (0, import_citty.defineCommand)({
+  meta: {
+    name: "eject",
+    description: "Eject Takeout documentation files into your project"
+  },
+  args: {
+    yes: {
+      type: "boolean",
+      description: "Skip confirmations and eject all files",
+      default: false
+    }
+  },
+  async run({
+    args
+  }) {
+    const cwd = process.cwd();
+    const targetDocsDir = (0, import_node_path.join)(cwd, "docs");
+    const sourceDocsDir = DOCS_DIR;
+    console.info();
+    console.info(import_picocolors.default.bold(import_picocolors.default.cyan("\u{1F4DA} Eject Docs")));
+    console.info();
+    console.info(import_picocolors.default.dim(`Source: ${sourceDocsDir}`));
+    console.info(import_picocolors.default.dim(`Target: ${targetDocsDir}`));
+    console.info();
+    if (!(0, import_node_fs.existsSync)(sourceDocsDir)) {
+      console.error(import_picocolors.default.red("\u2717 Source docs directory not found in Takeout package"));
+      process.exit(1);
+    }
+    if (!(0, import_node_fs.existsSync)(targetDocsDir)) {
+      console.info(import_picocolors.default.yellow("\u26A0 Target docs directory does not exist, will create it"));
+      (0, import_node_fs.mkdirSync)(targetDocsDir, {
+        recursive: true
+      });
+    }
+    const sourceFiles = (0, import_node_fs.readdirSync)(sourceDocsDir).filter(f => f.endsWith(".md"));
+    if (sourceFiles.length === 0) {
+      console.info(import_picocolors.default.yellow("No markdown files found in Takeout docs"));
+      return;
+    }
+    const filesToSync = [];
+    const stats = {
+      new: 0,
+      modified: 0,
+      identical: 0
+    };
+    for (const file of sourceFiles) {
+      const sourcePath = (0, import_node_path.join)(sourceDocsDir, file);
+      const targetPath = (0, import_node_path.join)(targetDocsDir, file);
+      const status = (0, import_sync.compareFiles)(sourcePath, targetPath);
+      stats[status]++;
+      filesToSync.push({
+        name: file,
+        sourcePath,
+        targetPath,
+        status,
+        sourceSize: (0, import_sync.getFileSize)(sourcePath),
+        targetSize: (0, import_sync.getFileSize)(targetPath)
+      });
+    }
+    console.info(import_picocolors.default.bold("Summary:"));
+    console.info(`  ${import_picocolors.default.green(`${stats.new} new`)}`);
+    console.info(`  ${import_picocolors.default.yellow(`${stats.modified} modified`)}`);
+    console.info(`  ${import_picocolors.default.dim(`${stats.identical} identical`)}`);
+    console.info();
+    if (stats.new === 0 && stats.modified === 0) {
+      console.info(import_picocolors.default.green("\u2713 All docs are already up to date!"));
+      return;
+    }
+    const sortOrder = {
+      new: 0,
+      modified: 1,
+      identical: 2
+    };
+    filesToSync.sort((a, b) => sortOrder[a.status] - sortOrder[b.status]);
+    let syncedCount = 0;
+    for (const file of filesToSync) {
+      if (args.yes && file.status !== "identical") {
+        const targetDir = (0, import_node_path.join)(targetDocsDir);
+        if (!(0, import_node_fs.existsSync)(targetDir)) {
+          (0, import_node_fs.mkdirSync)(targetDir, {
+            recursive: true
+          });
+        }
+        const content = (0, import_node_fs.readFileSync)(file.sourcePath);
+        (0, import_node_fs.writeFileSync)(file.targetPath, content);
+        console.info(import_picocolors.default.green(`  \u2713 ${file.name}`));
+        syncedCount++;
+      } else {
+        const wasSynced = await (0, import_sync.syncFileWithConfirmation)(file);
+        if (wasSynced) {
+          syncedCount++;
+        }
+      }
+    }
+    console.info();
+    console.info(import_picocolors.default.bold(import_picocolors.default.green(`\u2713 Complete: ${syncedCount} file(s) ejected`)));
+    console.info();
+  }
+});
 const docsCommand = (0, import_citty.defineCommand)({
   meta: {
     name: "docs",
-    description: "List and retrieve repository documentation"
+    description: "List and retrieve Takeout documentation"
   },
   subCommands: {
     list: listCommand,
     get: getCommand,
-    path: pathCommand
+    path: pathCommand,
+    eject: ejectCommand
   }
 });

package/dist/cjs/commands/onboard.cjs

@@ -285,7 +285,7 @@ const onboardCommand = (0, import_citty.defineCommand)({
       console.info();
       console.info("  bun ios            # build iOS dev app");
       console.info("  bun android        # build Android dev app");
-      console.info("  bun tko docs list  # view repository docs");
+      console.info("  bun tko docs list  # view Takeout docs");
       console.info();
     }
     if (startStep !== "production") {
@@ -690,7 +690,7 @@ async function setupUncloudDeployment(cwd) {
   console.info(import_picocolors.default.gray("   uc machine add --name server-2 root@IP"));
   console.info(import_picocolors.default.gray("   uc scale web 3    # run 3 instances"));
   console.info();
-  console.info(import_picocolors.default.gray("view detailed guide: bun tko docs get deploy-uncloud"));
+  console.info(import_picocolors.default.gray("view detailed guide: bun tko docs read deployment-uncloud"));
   console.info(import_picocolors.default.gray("or see: docs/deployment-uncloud.md"));
 }
 async function setupSSTDeployment(cwd) {

package/dist/cjs/commands/skills.cjs

@@ -37,9 +37,18 @@ __export(skills_exports, {
 });
 module.exports = __toCommonJS(skills_exports);
 var import_node_fs = require("node:fs");
+var import_node_module = require("node:module");
 var import_node_path = require("node:path");
 var import_citty = require("citty");
 var import_picocolors = __toESM(require("picocolors"), 1);
+const import_meta = {};
+const require2 = (0, import_node_module.createRequire)(import_meta.url);
+let DOCS_DIR;
+try {
+  DOCS_DIR = (0, import_node_path.dirname)(require2.resolve("@take-out/docs/package.json"));
+} catch {
+  DOCS_DIR = "";
+}
 const SKILL_PREFIX = "takeout-";
 function hasSkillFrontmatter(content) {
   if (!content.startsWith("---")) return false;
@@ -62,6 +71,7 @@ function resolveLocalDocsDir(cwd) {
 }
 function collectAllDocs(cwd) {
   const docs = [];
+  const seen = /* @__PURE__ */new Set();
   const localDocsDir = resolveLocalDocsDir(cwd);
   if ((0, import_node_fs.existsSync)(localDocsDir)) {
     const files = (0, import_node_fs.readdirSync)(localDocsDir).filter(f => f.endsWith(".md"));
@@ -69,8 +79,23 @@ function collectAllDocs(cwd) {
       const name = file.replace(/\.md$/, "");
       docs.push({
         name,
-        path: (0, import_node_path.join)(localDocsDir, file)
+        path: (0, import_node_path.join)(localDocsDir, file),
+        source: "local"
       });
+      seen.add(name);
+    }
+  }
+  if (DOCS_DIR && (0, import_node_fs.existsSync)(DOCS_DIR)) {
+    const files = (0, import_node_fs.readdirSync)(DOCS_DIR).filter(f => f.endsWith(".md"));
+    for (const file of files) {
+      const name = file.replace(/\.md$/, "");
+      if (!seen.has(name)) {
+        docs.push({
+          name,
+          path: (0, import_node_path.join)(DOCS_DIR, file),
+          source: "package"
+        });
+      }
     }
   }
   return docs;
@@ -140,7 +165,8 @@ async function generateDocSkills(cwd, clean) {
       if (!shouldCreate) continue;
       (0, import_node_fs.symlinkSync)(relativePath, skillFile);
       symlinked++;
-      console.info(`  ${import_picocolors.default.green("\u27F7")} ${skillName} ${import_picocolors.default.dim("(symlink)")}`);
+      const sourceLabel = doc.source === "local" ? import_picocolors.default.blue("local") : import_picocolors.default.dim("package");
+      console.info(`  ${import_picocolors.default.green("\u27F7")} ${skillName} ${sourceLabel} ${import_picocolors.default.dim("(symlink)")}`);
     } else {
       if (!hasFrontmatter) {
         skipped++;
@@ -168,7 +194,7 @@ async function generateDocSkills(cwd, clean) {
       if (stat.isSymbolicLink()) {
         const linkTarget = (0, import_node_fs.readlinkSync)(skillFile);
         const resolvedTarget = (0, import_node_path.resolve)(skillDir, linkTarget);
-        shouldUnlink = resolvedTarget.startsWith(`${localDocsDir}/`);
+        shouldUnlink = resolvedTarget.startsWith(`${localDocsDir}/`) || !!DOCS_DIR && resolvedTarget.startsWith(`${DOCS_DIR}/`);
       }
     } catch {}
     if (!shouldUnlink) continue;

package/dist/cjs/commands/sync.cjs

@@ -40,18 +40,29 @@ var import_node_child_process = require("node:child_process");
 var import_node_fs = require("node:fs");
 var import_node_os = require("node:os");
 var import_node_path = require("node:path");
+var import_node_url = require("node:url");
 var import_citty = require("citty");
 var import_picocolors = __toESM(require("picocolors"), 1);
 var import_prompts = require("../utils/prompts.cjs");
+const import_meta = {};
 const UPSTREAM_REPO = "tamagui/takeout2";
 const UPSTREAM_REMOTE = "takeout-upstream";
 const TAKEOUT_FILE = ".takeout";
 function getSyncPrompt() {
-  const promptPath = (0, import_node_path.join)(process.cwd(), "docs", "upgrade.md");
-  if (!(0, import_node_fs.existsSync)(promptPath)) {
-    throw new Error("Missing docs/upgrade.md. Copy it from https://github.com/tamagui/takeout2/blob/main/docs/upgrade.md and rerun `bun tko sync`.");
+  try {
+    const currentDir = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+    let monorepoRoot = currentDir;
+    while (monorepoRoot !== (0, import_node_path.parse)(monorepoRoot).root) {
+      const promptPath = (0, import_node_path.join)(monorepoRoot, "packages", "docs", "sync-prompt.md");
+      if ((0, import_node_fs.existsSync)(promptPath)) {
+        return (0, import_node_fs.readFileSync)(promptPath, "utf-8");
+      }
+      monorepoRoot = (0, import_node_path.dirname)(monorepoRoot);
+    }
+    throw new Error("Could not find sync-prompt.md in packages/docs");
+  } catch (error) {
+    throw new Error(`Could not load sync prompt: ${error instanceof Error ? error.message : "Unknown error"}`);
   }
-  return (0, import_node_fs.readFileSync)(promptPath, "utf-8");
 }
 function checkToolAvailable(command) {
   try {