@catladder/cli 0.0.0-next-80fd0ab4 → 0.0.0-next-ebc933f2

package/dist/bundles/catenv/index.js

@@ -1533,6 +1533,224 @@ exports.updateSecretsCache = updateSecretsCache;
 
 /***/ }),
 
+/***/ 22383:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+exports.generateAgentSkills = exports.injectGeneratedMarker = exports.AGENT_SKILL_GENERATED_MARKER = void 0;
+const fs_1 = __nccwpck_require__(79896);
+const promises_1 = __nccwpck_require__(91943);
+const path_1 = __nccwpck_require__(16928);
+const shippedSkills_1 = __nccwpck_require__(49708);
+const types_1 = __nccwpck_require__(59260);
+/**
+ * marks a materialized skill file as generated. Cleanup only ever
+ * removes skill directories whose SKILL.md carries this marker, so a
+ * user's own skills are never touched — even if they picked a
+ * `catladder-*` name.
+ */
+exports.AGENT_SKILL_GENERATED_MARKER = "<!-- 🐱 🔨 generated by catladder — do not edit manually, this file is overwritten on every catenv run -->";
+/**
+ * inserts the generated-marker into a markdown file: after the YAML
+ * frontmatter when there is one (a leading comment would break
+ * frontmatter parsing), at the top otherwise
+ */
+const injectGeneratedMarker = content => {
+  if (content.startsWith("---\n")) {
+    const frontmatterEnd = content.indexOf("\n---\n", 3);
+    if (frontmatterEnd !== -1) {
+      const bodyStart = frontmatterEnd + "\n---\n".length;
+      return content.slice(0, bodyStart) + "\n" + exports.AGENT_SKILL_GENERATED_MARKER + "\n" + content.slice(bodyStart);
+    }
+  }
+  return exports.AGENT_SKILL_GENERATED_MARKER + "\n\n" + content;
+};
+exports.injectGeneratedMarker = injectGeneratedMarker;
+/**
+ * removes previously materialized catladder skills from ALL known
+ * target directories (not just the enabled ones), so that opting out
+ * or narrowing the targets doesn't leave stale copies behind
+ */
+const cleanupGeneratedAgentSkills = async rootDir => {
+  for (const targetDir of Object.values(types_1.AGENT_SKILL_TARGET_DIRS)) {
+    const skillsRoot = (0, path_1.join)(rootDir, targetDir);
+    if (!(0, fs_1.existsSync)(skillsRoot)) continue;
+    for (const entry of await (0, promises_1.readdir)(skillsRoot)) {
+      if (!entry.startsWith(shippedSkills_1.AGENT_SKILL_PREFIX)) continue;
+      const skillMd = (0, path_1.join)(skillsRoot, entry, "SKILL.md");
+      if (!(0, fs_1.existsSync)(skillMd)) continue;
+      const content = await (0, promises_1.readFile)(skillMd, "utf-8");
+      if (!content.includes(exports.AGENT_SKILL_GENERATED_MARKER)) continue;
+      await (0, promises_1.rm)((0, path_1.join)(skillsRoot, entry), {
+        recursive: true,
+        force: true
+      });
+    }
+  }
+};
+/**
+ * materializes the agent skills shipped with catladder (usage guides
+ * for AI coding agents) into the repository's agent skill directories,
+ * so agents working in the project use knowledge matching the installed
+ * catladder version. Opt out or narrow the targets via
+ * `agentSkills` in the config.
+ */
+const generateAgentSkills = async (context, rootDir = ".") => {
+  await cleanupGeneratedAgentSkills(rootDir);
+  const targets = (0, types_1.getAgentSkillTargets)(context.config.agentSkills);
+  if (targets.length === 0) return;
+  const skills = (0, shippedSkills_1.getShippedSkills)();
+  for (const target of targets) {
+    for (const skill of skills) {
+      for (const file of skill.files) {
+        const path = (0, path_1.join)(rootDir, types_1.AGENT_SKILL_TARGET_DIRS[target], skill.name, file.relativePath);
+        await (0, promises_1.mkdir)((0, path_1.dirname)(path), {
+          recursive: true
+        });
+        const content = file.relativePath.endsWith(".md") ? (0, exports.injectGeneratedMarker)(file.content) : file.content;
+        await context.fileWriter.writeGeneratedFileRaw(path, content);
+      }
+    }
+  }
+};
+exports.generateAgentSkills = generateAgentSkills;
+
+/***/ }),
+
+/***/ 8853:
+/***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
+
+"use strict";
+
+
+var __createBinding = this && this.__createBinding || (Object.create ? function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  var desc = Object.getOwnPropertyDescriptor(m, k);
+  if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+    desc = {
+      enumerable: true,
+      get: function () {
+        return m[k];
+      }
+    };
+  }
+  Object.defineProperty(o, k2, desc);
+} : function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  o[k2] = m[k];
+});
+var __exportStar = this && this.__exportStar || function (m, exports) {
+  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+__exportStar(__nccwpck_require__(59260), exports);
+__exportStar(__nccwpck_require__(49708), exports);
+__exportStar(__nccwpck_require__(22383), exports);
+
+/***/ }),
+
+/***/ 49708:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+exports.getShippedSkills = exports.getShippedSkillsDir = exports.AGENT_SKILL_PREFIX = void 0;
+const fs_1 = __nccwpck_require__(79896);
+const path_1 = __nccwpck_require__(16928);
+/**
+ * all catladder skills use this prefix; it marks the namespace
+ * catladder owns inside the agent skill directories (regeneration may
+ * remove stale `catladder-*` skills it generated earlier)
+ */
+exports.AGENT_SKILL_PREFIX = "catladder-";
+/**
+ * the directory containing the agent skill definitions shipped with
+ * the package (copied into dist at build time; the repository layout
+ * is the fallback for development and tests)
+ */
+const getShippedSkillsDir = () => {
+  const candidates = [
+  // built pipeline package: dist/agentSkills -> dist/skills
+  // bundled cli package (what consumers install): the ncc bundles live
+  // in dist/bundles/<name>, so both resolve to dist/bundles/skills
+  (0, path_1.join)(__dirname, "..", "skills"),
+  // cli tsc dist (catenv-dev): dist/pipeline/src/agentSkills -> dist/skills
+  // repository: pipeline/src/agentSkills -> <root>/skills
+  (0, path_1.join)(__dirname, "..", "..", "..", "skills")];
+  const found = candidates.find(candidate => (0, fs_1.existsSync)(candidate));
+  if (!found) {
+    throw new Error("shipped agent skill definitions not found");
+  }
+  return found;
+};
+exports.getShippedSkillsDir = getShippedSkillsDir;
+const readFilesRecursively = (dir, relativeTo) => (0, fs_1.readdirSync)(dir).sort().flatMap(entry => {
+  const fullPath = (0, path_1.join)(dir, entry);
+  if ((0, fs_1.statSync)(fullPath).isDirectory()) {
+    return readFilesRecursively(fullPath, relativeTo);
+  }
+  return [{
+    relativePath: fullPath.slice(relativeTo.length + 1),
+    content: (0, fs_1.readFileSync)(fullPath, "utf-8")
+  }];
+});
+const getShippedSkills = () => {
+  const skillsDir = (0, exports.getShippedSkillsDir)();
+  return (0, fs_1.readdirSync)(skillsDir).sort().filter(entry => (0, fs_1.statSync)((0, path_1.join)(skillsDir, entry)).isDirectory()).map(name => {
+    const skillDir = (0, path_1.join)(skillsDir, name);
+    return {
+      name,
+      files: readFilesRecursively(skillDir, skillDir)
+    };
+  });
+};
+exports.getShippedSkills = getShippedSkills;
+
+/***/ }),
+
+/***/ 59260:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+exports.getAgentSkillTargets = exports.AGENT_SKILL_TARGET_DIRS = void 0;
+/**
+ * where agent skills get materialized, per agent ecosystem:
+ * - claude-code: the Claude Code project skills directory
+ * - agents: the cross-agent universal skills directory
+ *   (https://agents.md convention, picked up by Cursor, Codex, ...)
+ */
+exports.AGENT_SKILL_TARGET_DIRS = {
+  "claude-code": ".claude/skills",
+  agents: ".agents/skills"
+};
+const getAgentSkillTargets = agentSkills => {
+  var _a;
+  if (agentSkills === false) return [];
+  if (agentSkills === true || agentSkills === undefined) {
+    return Object.keys(exports.AGENT_SKILL_TARGET_DIRS);
+  }
+  return (_a = agentSkills.targets) !== null && _a !== void 0 ? _a : Object.keys(exports.AGENT_SKILL_TARGET_DIRS);
+};
+exports.getAgentSkillTargets = getAgentSkillTargets;
+
+/***/ }),
+
 /***/ 54038:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -5370,7 +5588,7 @@ Object.defineProperty(exports, "__esModule", ({
   value: true
 }));
 exports.DOCKER_REGISTRY = exports.PIPELINE_IMAGE_TAG = void 0;
-exports.PIPELINE_IMAGE_TAG = "next-80fd0ab4" || 0;
+exports.PIPELINE_IMAGE_TAG = "next-ebc933f2" || 0;
 exports.DOCKER_REGISTRY = "git.panter.ch:5001/catladder/catladder" || 0;
 
 /***/ }),
@@ -9515,6 +9733,7 @@ const backends_1 = __nccwpck_require__(93243);
 const gitlab_1 = __nccwpck_require__(8475);
 const jobImagesPlan_1 = __nccwpck_require__(11585);
 const shippedCatci_1 = __nccwpck_require__(93401);
+const agentSkills_1 = __nccwpck_require__(8853);
 /**
  * generates the pipeline files of all pipeline types enabled in the
  * config (see `pipelines`). Pass an explicit `pipelineType` to generate
@@ -9536,6 +9755,9 @@ async function generatePipelineFiles(context, pipelineType) {
       recursive: true,
       force: true
     });
+    // agent skills are backend-independent, materialized once per full
+    // generation
+    await (0, agentSkills_1.generateAgentSkills)(context);
   }
   for (const type of pipelineTypes) {
     await generatePipelineFilesForBackend(context, (0, backends_1.getPipelineBackend)(type));

package/dist/bundles/cli/index.js

@@ -7581,6 +7581,224 @@ exports.updateSecretsCache = updateSecretsCache;
 
 /***/ }),
 
+/***/ 22383:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+exports.generateAgentSkills = exports.injectGeneratedMarker = exports.AGENT_SKILL_GENERATED_MARKER = void 0;
+const fs_1 = __nccwpck_require__(79896);
+const promises_1 = __nccwpck_require__(91943);
+const path_1 = __nccwpck_require__(16928);
+const shippedSkills_1 = __nccwpck_require__(49708);
+const types_1 = __nccwpck_require__(59260);
+/**
+ * marks a materialized skill file as generated. Cleanup only ever
+ * removes skill directories whose SKILL.md carries this marker, so a
+ * user's own skills are never touched — even if they picked a
+ * `catladder-*` name.
+ */
+exports.AGENT_SKILL_GENERATED_MARKER = "<!-- 🐱 🔨 generated by catladder — do not edit manually, this file is overwritten on every catenv run -->";
+/**
+ * inserts the generated-marker into a markdown file: after the YAML
+ * frontmatter when there is one (a leading comment would break
+ * frontmatter parsing), at the top otherwise
+ */
+const injectGeneratedMarker = content => {
+  if (content.startsWith("---\n")) {
+    const frontmatterEnd = content.indexOf("\n---\n", 3);
+    if (frontmatterEnd !== -1) {
+      const bodyStart = frontmatterEnd + "\n---\n".length;
+      return content.slice(0, bodyStart) + "\n" + exports.AGENT_SKILL_GENERATED_MARKER + "\n" + content.slice(bodyStart);
+    }
+  }
+  return exports.AGENT_SKILL_GENERATED_MARKER + "\n\n" + content;
+};
+exports.injectGeneratedMarker = injectGeneratedMarker;
+/**
+ * removes previously materialized catladder skills from ALL known
+ * target directories (not just the enabled ones), so that opting out
+ * or narrowing the targets doesn't leave stale copies behind
+ */
+const cleanupGeneratedAgentSkills = async rootDir => {
+  for (const targetDir of Object.values(types_1.AGENT_SKILL_TARGET_DIRS)) {
+    const skillsRoot = (0, path_1.join)(rootDir, targetDir);
+    if (!(0, fs_1.existsSync)(skillsRoot)) continue;
+    for (const entry of await (0, promises_1.readdir)(skillsRoot)) {
+      if (!entry.startsWith(shippedSkills_1.AGENT_SKILL_PREFIX)) continue;
+      const skillMd = (0, path_1.join)(skillsRoot, entry, "SKILL.md");
+      if (!(0, fs_1.existsSync)(skillMd)) continue;
+      const content = await (0, promises_1.readFile)(skillMd, "utf-8");
+      if (!content.includes(exports.AGENT_SKILL_GENERATED_MARKER)) continue;
+      await (0, promises_1.rm)((0, path_1.join)(skillsRoot, entry), {
+        recursive: true,
+        force: true
+      });
+    }
+  }
+};
+/**
+ * materializes the agent skills shipped with catladder (usage guides
+ * for AI coding agents) into the repository's agent skill directories,
+ * so agents working in the project use knowledge matching the installed
+ * catladder version. Opt out or narrow the targets via
+ * `agentSkills` in the config.
+ */
+const generateAgentSkills = async (context, rootDir = ".") => {
+  await cleanupGeneratedAgentSkills(rootDir);
+  const targets = (0, types_1.getAgentSkillTargets)(context.config.agentSkills);
+  if (targets.length === 0) return;
+  const skills = (0, shippedSkills_1.getShippedSkills)();
+  for (const target of targets) {
+    for (const skill of skills) {
+      for (const file of skill.files) {
+        const path = (0, path_1.join)(rootDir, types_1.AGENT_SKILL_TARGET_DIRS[target], skill.name, file.relativePath);
+        await (0, promises_1.mkdir)((0, path_1.dirname)(path), {
+          recursive: true
+        });
+        const content = file.relativePath.endsWith(".md") ? (0, exports.injectGeneratedMarker)(file.content) : file.content;
+        await context.fileWriter.writeGeneratedFileRaw(path, content);
+      }
+    }
+  }
+};
+exports.generateAgentSkills = generateAgentSkills;
+
+/***/ }),
+
+/***/ 8853:
+/***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
+
+"use strict";
+
+
+var __createBinding = this && this.__createBinding || (Object.create ? function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  var desc = Object.getOwnPropertyDescriptor(m, k);
+  if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+    desc = {
+      enumerable: true,
+      get: function () {
+        return m[k];
+      }
+    };
+  }
+  Object.defineProperty(o, k2, desc);
+} : function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  o[k2] = m[k];
+});
+var __exportStar = this && this.__exportStar || function (m, exports) {
+  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+__exportStar(__nccwpck_require__(59260), exports);
+__exportStar(__nccwpck_require__(49708), exports);
+__exportStar(__nccwpck_require__(22383), exports);
+
+/***/ }),
+
+/***/ 49708:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+exports.getShippedSkills = exports.getShippedSkillsDir = exports.AGENT_SKILL_PREFIX = void 0;
+const fs_1 = __nccwpck_require__(79896);
+const path_1 = __nccwpck_require__(16928);
+/**
+ * all catladder skills use this prefix; it marks the namespace
+ * catladder owns inside the agent skill directories (regeneration may
+ * remove stale `catladder-*` skills it generated earlier)
+ */
+exports.AGENT_SKILL_PREFIX = "catladder-";
+/**
+ * the directory containing the agent skill definitions shipped with
+ * the package (copied into dist at build time; the repository layout
+ * is the fallback for development and tests)
+ */
+const getShippedSkillsDir = () => {
+  const candidates = [
+  // built pipeline package: dist/agentSkills -> dist/skills
+  // bundled cli package (what consumers install): the ncc bundles live
+  // in dist/bundles/<name>, so both resolve to dist/bundles/skills
+  (0, path_1.join)(__dirname, "..", "skills"),
+  // cli tsc dist (catenv-dev): dist/pipeline/src/agentSkills -> dist/skills
+  // repository: pipeline/src/agentSkills -> <root>/skills
+  (0, path_1.join)(__dirname, "..", "..", "..", "skills")];
+  const found = candidates.find(candidate => (0, fs_1.existsSync)(candidate));
+  if (!found) {
+    throw new Error("shipped agent skill definitions not found");
+  }
+  return found;
+};
+exports.getShippedSkillsDir = getShippedSkillsDir;
+const readFilesRecursively = (dir, relativeTo) => (0, fs_1.readdirSync)(dir).sort().flatMap(entry => {
+  const fullPath = (0, path_1.join)(dir, entry);
+  if ((0, fs_1.statSync)(fullPath).isDirectory()) {
+    return readFilesRecursively(fullPath, relativeTo);
+  }
+  return [{
+    relativePath: fullPath.slice(relativeTo.length + 1),
+    content: (0, fs_1.readFileSync)(fullPath, "utf-8")
+  }];
+});
+const getShippedSkills = () => {
+  const skillsDir = (0, exports.getShippedSkillsDir)();
+  return (0, fs_1.readdirSync)(skillsDir).sort().filter(entry => (0, fs_1.statSync)((0, path_1.join)(skillsDir, entry)).isDirectory()).map(name => {
+    const skillDir = (0, path_1.join)(skillsDir, name);
+    return {
+      name,
+      files: readFilesRecursively(skillDir, skillDir)
+    };
+  });
+};
+exports.getShippedSkills = getShippedSkills;
+
+/***/ }),
+
+/***/ 59260:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+
+Object.defineProperty(exports, "__esModule", ({
+  value: true
+}));
+exports.getAgentSkillTargets = exports.AGENT_SKILL_TARGET_DIRS = void 0;
+/**
+ * where agent skills get materialized, per agent ecosystem:
+ * - claude-code: the Claude Code project skills directory
+ * - agents: the cross-agent universal skills directory
+ *   (https://agents.md convention, picked up by Cursor, Codex, ...)
+ */
+exports.AGENT_SKILL_TARGET_DIRS = {
+  "claude-code": ".claude/skills",
+  agents: ".agents/skills"
+};
+const getAgentSkillTargets = agentSkills => {
+  var _a;
+  if (agentSkills === false) return [];
+  if (agentSkills === true || agentSkills === undefined) {
+    return Object.keys(exports.AGENT_SKILL_TARGET_DIRS);
+  }
+  return (_a = agentSkills.targets) !== null && _a !== void 0 ? _a : Object.keys(exports.AGENT_SKILL_TARGET_DIRS);
+};
+exports.getAgentSkillTargets = getAgentSkillTargets;
+
+/***/ }),
+
 /***/ 54038:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -11418,7 +11636,7 @@ Object.defineProperty(exports, "__esModule", ({
   value: true
 }));
 exports.DOCKER_REGISTRY = exports.PIPELINE_IMAGE_TAG = void 0;
-exports.PIPELINE_IMAGE_TAG = "next-80fd0ab4" || 0;
+exports.PIPELINE_IMAGE_TAG = "next-ebc933f2" || 0;
 exports.DOCKER_REGISTRY = "git.panter.ch:5001/catladder/catladder" || 0;
 
 /***/ }),
@@ -15563,6 +15781,7 @@ const backends_1 = __nccwpck_require__(93243);
 const gitlab_1 = __nccwpck_require__(8475);
 const jobImagesPlan_1 = __nccwpck_require__(11585);
 const shippedCatci_1 = __nccwpck_require__(93401);
+const agentSkills_1 = __nccwpck_require__(8853);
 /**
  * generates the pipeline files of all pipeline types enabled in the
  * config (see `pipelines`). Pass an explicit `pipelineType` to generate
@@ -15584,6 +15803,9 @@ async function generatePipelineFiles(context, pipelineType) {
       recursive: true,
       force: true
     });
+    // agent skills are backend-independent, materialized once per full
+    // generation
+    await (0, agentSkills_1.generateAgentSkills)(context);
   }
   for (const type of pipelineTypes) {
     await generatePipelineFilesForBackend(context, (0, backends_1.getPipelineBackend)(type));

package/dist/bundles/skills/catladder-cli/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: catladder-cli
+description: How to invoke the catladder CLI non-interactively — command structure, passing inputs via flags or --inputs JSON, skipping prompts, and the full generated command reference. Use when running any `catladder` command (project setup, doctor, secrets, k8s, ci, cloudsql, mongo) or when unsure which catladder command exists for a task. Triggers on "catladder command", "yarn catladder", "project doctor", "project setup", "run catladder".
+---
+
+# Using the catladder CLI
+
+catladder is installed per project — invoke it as `yarn catladder`
+(never a globally installed copy). Every command can run
+non-interactively, which is the mode agents should use.
+
+## Invocation
+
+```sh
+yarn catladder <command...> [args] [flags]
+
+# examples
+yarn catladder project doctor
+yarn catladder project ci job-log
+yarn catladder --help                 # command tree
+yarn catladder project --help         # subcommands of a group
+```
+
+## Passing inputs
+
+Commands declare typed inputs. Any input not provided on the command
+line is prompted for interactively — in a non-interactive context
+(agents!) provide them up front:
+
+- positional inputs: `yarn catladder project k8s list-pods dev:api`
+- flag per input: `--some-input value` (kebab-case of the input name),
+  booleans as `--flag` / `--no-flag`
+- all at once as JSON: `--inputs '{"envComponent": "dev:api"}'`
+- `-y` / `--yes` skips confirmation prompts
+
+A missing required input fails with a message naming the exact flag to
+pass. Environment/component selectors use the `env:component` form
+(e.g. `dev:api`, `review-123:www`).
+
+Some commands are inherently interactive (e.g.
+`project config-secrets` opens `$EDITOR`) — ask the user to run those.
+
+## Command reference
+
+See [references/commands.md](references/commands.md) for all commands
+with their descriptions and inputs (generated from the CLI itself, so
+it matches the installed version).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-secrets` — env vars and secret management
+- `catladder-pipelines` — pipeline behavior and CI debugging