@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/kata/gitignore.ts

@@ -0,0 +1,165 @@
+/**
+ * Kata bootstrappers for .gitignore and PREFERENCES.md
+ *
+ * Ensures baseline .gitignore exists with universally-correct patterns.
+ * Creates an empty PREFERENCES.md template if it doesn't exist.
+ * Both idempotent — non-destructive if already present.
+ */
+
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/**
+ * Patterns that are always correct regardless of project type.
+ * No one ever wants these tracked.
+ */
+const BASELINE_PATTERNS = [
+  // ── Kata runtime (not source artifacts) ──
+  ".kata/activity/",
+  ".kata/runtime/",
+  ".kata/auto.lock",
+  ".kata/metrics.json",
+  ".kata/STATE.md",
+
+  // ── OS junk ──
+  ".DS_Store",
+  "Thumbs.db",
+
+  // ── Editor / IDE ──
+  "*.swp",
+  "*.swo",
+  "*~",
+  ".idea/",
+  ".vscode/",
+  "*.code-workspace",
+
+  // ── Environment / secrets ──
+  ".env",
+  ".env.*",
+  "!.env.example",
+
+  // ── Node / JS / TS ──
+  "node_modules/",
+  ".next/",
+  "dist/",
+  "build/",
+
+  // ── Python ──
+  "__pycache__/",
+  "*.pyc",
+  ".venv/",
+  "venv/",
+
+  // ── Rust ──
+  "target/",
+
+  // ── Go ──
+  "vendor/",
+
+  // ── Misc build artifacts ──
+  "*.log",
+  "coverage/",
+  ".cache/",
+  "tmp/",
+];
+
+/**
+ * Ensure basePath/.gitignore contains all baseline patterns.
+ * Creates the file if missing; appends only missing lines if it exists.
+ * Returns true if the file was created or modified, false if already complete.
+ */
+export function ensureGitignore(basePath: string): boolean {
+  const gitignorePath = join(basePath, ".gitignore");
+
+  let existing = "";
+  if (existsSync(gitignorePath)) {
+    existing = readFileSync(gitignorePath, "utf-8");
+  }
+
+  // Parse existing lines (trimmed, ignoring comments and blanks)
+  const existingLines = new Set(
+    existing
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#")),
+  );
+
+  // Find patterns not yet present
+  const missing = BASELINE_PATTERNS.filter((p) => !existingLines.has(p));
+
+  if (missing.length === 0) return false;
+
+  // Build the block to append
+  const block = [
+    "",
+    "# ── Kata baseline (auto-generated) ──",
+    ...missing,
+    "",
+  ].join("\n");
+
+  // Ensure existing content ends with a newline before appending
+  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
+  writeFileSync(gitignorePath, existing + prefix + block, "utf-8");
+
+  return true;
+}
+
+/**
+ * Ensure basePath/.kata/PREFERENCES.md exists as an empty template.
+ * Creates the file with frontmatter only if it doesn't exist.
+ * Returns true if created, false if already exists.
+ */
+export function ensurePreferences(basePath: string): boolean {
+  const preferencesPath = join(basePath, ".kata", "PREFERENCES.md");
+
+  if (existsSync(preferencesPath)) {
+    return false;
+  }
+
+  const template = `---
+version: 1
+always_use_skills: []
+prefer_skills: []
+avoid_skills: []
+skill_rules: []
+custom_instructions: []
+models: {}
+skill_discovery: {}
+auto_supervisor: {}
+---
+
+# Kata Skill Preferences
+
+Project-specific guidance for skill selection and execution preferences.
+
+See \`~/.kata-cli/agent/extensions/kata/docs/preferences-reference.md\` for full field documentation and examples.
+
+## Fields
+
+- \`always_use_skills\`: Skills that must be available during all Kata operations
+- \`prefer_skills\`: Skills to prioritize when multiple options exist
+- \`avoid_skills\`: Skills to minimize or avoid (with lower priority than prefer)
+- \`skill_rules\`: Context-specific rules (e.g., "use tool X for Y type of work")
+- \`custom_instructions\`: Append-only project guidance (do not override system rules)
+- \`models\`: Model preferences for specific task types
+- \`skill_discovery\`: Automatic skill detection preferences
+- \`auto_supervisor\`: Supervision and gating rules for autonomous modes
+
+## Examples
+
+\`\`\`yaml
+prefer_skills:
+  - playwright
+  - resolve_library
+avoid_skills:
+  - subagent  # prefer direct execution in this project
+
+custom_instructions:
+  - "Always verify with browser_assert before marking UI work done"
+  - "Use Context7 for all library/framework decisions"
+\`\`\`
+`;
+
+  writeFileSync(preferencesPath, template, "utf-8");
+  return true;
+}