trackerctl 0.2.0 → 0.3.0

package/README.md

@@ -28,16 +28,19 @@ bun run build          # bundle to dist/tracker.js (what the npm package ships)
 
 ## Configuration
 
-Copy `tracker.config.example.json` to `tracker.config.json` and fill in your instance:
+In the project root, scaffold a config:
 
 ```sh
-cp tracker.config.example.json tracker.config.json
+tracker init --base-url https://gitlab.example.com --project group/project
+# or `tracker init` alone, then edit the placeholders
 ```
 
-`tracker.config.json` is **gitignored** (it carries instance/project identifiers); the
-committed example holds the shape. The token is also never committed (env var or gitignored
-`.env`). Config discovery walks up from the current directory, so any subdirectory of the
-project works.
+`init` writes `tracker.config.json` and — inside a git repository — git-ignores the
+local-only files (`tracker.config.json`, `.tracker/`, `.env`) so instance and project
+identifiers can never be committed. The committed `tracker.config.example.json` holds the
+same shape if you prefer copying it by hand. The token is also never committed (env var or
+gitignored `.env`). Config discovery walks up from the current directory, so any
+subdirectory of the project works.
 
 ```json
 {

package/dist/tracker.js

@@ -2,8 +2,8 @@
 // @bun
 
 // src/cli/index.ts
-import { existsSync as existsSync3 } from "fs";
-import { resolve as resolve3 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { resolve as resolve4 } from "path";
 
 // src/errors.ts
 class DomainError extends Error {
@@ -758,7 +758,7 @@ function parseConfig(json, rootDir) {
 function loadConfig(startDir = process.cwd()) {
   const file = findConfigFile(startDir);
   if (!file) {
-    throw new UsageError(`no ${CONFIG_FILENAME} found in ${startDir} or any parent directory \u2014 create one (see README) or cd into the project.`);
+    throw new UsageError(`no ${CONFIG_FILENAME} found in ${startDir} or any parent directory \u2014 run \`tracker init\` to create one, or cd into the project.`);
   }
   return parseConfig(readFileSync2(file, "utf8"), dirname3(file));
 }
@@ -1105,11 +1105,83 @@ async function ensureFresh(adapter, cache, staleMs, nowMs = Date.now(), onSync)
   return true;
 }
 
+// src/init.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { dirname as dirname4, join as join3, resolve as resolve3 } from "path";
+var PLACEHOLDER_URL = "https://gitlab.example.com";
+var PLACEHOLDER_PROJECT = "group/project";
+function configTemplate(baseUrl, project) {
+  const config = {
+    provider: "gitlab",
+    gitlab: {
+      base_url: baseUrl.replace(/\/+$/, ""),
+      project,
+      token_env: ["TRACKER_GITLAB_TOKEN", "GITLAB_PERSONAL_ACCESS_TOKEN"],
+      native_blocking: true
+    },
+    labels: { in_progress: "status::in-progress" },
+    memory: { enabled: true, title: "\uD83D\uDCCC Project Memory", label: "meta::memory" },
+    cache: { path: ".tracker/cache.sqlite", stale_minutes: 15 }
+  };
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
+function ensureIgnored(dir, warnings) {
+  const gitRoot = findGitRoot(dir);
+  if (!gitRoot)
+    return [];
+  const entries = [
+    [CONFIG_FILENAME, join3(dir, CONFIG_FILENAME)],
+    [".tracker/", join3(dir, ".tracker", "cache.sqlite")],
+    [".env", join3(dir, ".env")]
+  ];
+  const added = [];
+  for (const [pattern, path] of entries) {
+    const ignored = isGitIgnored(gitRoot, path);
+    if (ignored === null) {
+      warnings.push(`git not available \u2014 verify ${pattern} is git-ignored yourself`);
+      return added;
+    }
+    if (ignored)
+      continue;
+    const gitignorePath = join3(dir, ".gitignore");
+    const existing = existsSync3(gitignorePath) ? readFileSync3(gitignorePath, "utf8") : "";
+    const prefix = existing && !existing.endsWith(`
+`) ? `
+` : "";
+    appendFileSync2(gitignorePath, `${prefix}${pattern}
+`);
+    added.push(pattern);
+  }
+  return added;
+}
+function initProject(targetDir, opts) {
+  const dir = resolve3(targetDir);
+  const configPath = join3(dir, CONFIG_FILENAME);
+  if (existsSync3(configPath)) {
+    throw new UsageError(`${configPath} already exists \u2014 edit it instead of re-running init`);
+  }
+  const warnings = [];
+  const parentConfig = findConfigFile(dirname4(dir));
+  if (parentConfig) {
+    warnings.push(`a ${CONFIG_FILENAME} already exists in ${dirname4(parentConfig)} \u2014 the one created here will shadow it for everything under ${dir}`);
+  }
+  const placeholders = !opts.baseUrl || !opts.project;
+  writeFileSync(configPath, configTemplate(opts.baseUrl ?? PLACEHOLDER_URL, opts.project ?? PLACEHOLDER_PROJECT));
+  const ignoreAdded = ensureIgnored(dir, warnings);
+  return { configPath, placeholders, ignoreAdded, warnings };
+}
+
 // src/cli/help.ts
 var HELP = `tracker \u2014 multi-backend issue tracking for humans and AI agents
 
 usage: tracker <command> [args]
 
+setup:
+  init [--base-url <url>] [--project <group/project>]
+                             scaffold tracker.config.json + .gitignore entries
+  doctor                     verify config, token, connectivity, capabilities
+
 read commands (local cache, auto-sync when stale; all accept --json):
   sync                       refresh the local cache from the provider
   ready [--parent <id>]      open + unblocked + unassigned + not in-progress
@@ -1121,7 +1193,6 @@ read commands (local cache, auto-sync when stale; all accept --json):
   users <query>              resolve usernames/names to user ids
   whoami                     the authenticated user
   memories [filter]          list project memories
-  doctor                     verify config, token, connectivity, capabilities
 
 write commands:
   create -t <title> [-d <desc>] [--parent <id>] [--epic <id>] [-l a,b]
@@ -1251,7 +1322,17 @@ example: tracker users mehmet`,
   whoami: "usage: tracker whoami [--json]",
   doctor: `usage: tracker doctor [--json]
 
-Verifies config, token, REST/GraphQL connectivity, capabilities, cache.`
+Verifies config, token, REST/GraphQL connectivity, capabilities, cache.`,
+  init: `usage: tracker init [--base-url <url>] [--project <group/project>]
+
+Scaffolds tracker.config.json in the current directory (placeholders when the
+flags are omitted) and, inside a git repository, git-ignores the local-only
+files (tracker.config.json, .tracker/, .env) so instance and project
+identifiers can never be committed. Refuses to overwrite an existing config.
+
+examples:
+  tracker init --base-url https://gitlab.example.com --project group/project
+  tracker init    # then edit the placeholders in tracker.config.json`
 };
 function commandHelp(cmd) {
   return PER_COMMAND[cmd] ?? HELP;
@@ -1340,8 +1421,8 @@ function buildCtx() {
     token,
     nativeBlocking: config.gitlab.native_blocking
   });
-  const cachePath = resolve3(config.rootDir, config.cache.path);
-  if (!existsSync3(cachePath)) {
+  const cachePath = resolve4(config.rootDir, config.cache.path);
+  if (!existsSync4(cachePath)) {
     const guard = guardCacheIgnored(config.rootDir, cachePath);
     if (guard.action === "added" || guard.action === "warn")
       console.error(`(${guard.detail})`);
@@ -1367,7 +1448,7 @@ async function cmdSync(ctx) {
   const t0 = performance.now();
   const { count } = await syncCache(ctx.adapter, ctx.cache);
   const ms = Math.round(performance.now() - t0);
-  console.log(`synced ${count} items in ${ms}ms \u2192 ${resolve3(ctx.config.rootDir, ctx.config.cache.path)}`);
+  console.log(`synced ${count} items in ${ms}ms \u2192 ${resolve4(ctx.config.rootDir, ctx.config.cache.path)}`);
 }
 async function cmdReady(ctx, args) {
   await freshen(ctx);
@@ -1617,7 +1698,7 @@ async function cmdDoctor(args) {
       name: "config",
       status: "fail",
       detail: e.message,
-      fix: "create tracker.config.json (see README) in the project root"
+      fix: "run `tracker init` in the project root to create tracker.config.json"
     });
   }
   let ctx = null;
@@ -1684,7 +1765,7 @@ async function cmdDoctor(args) {
       status: "ok",
       detail: last ? `${ctx.cache.count()} items, synced ${Math.round((Date.now() - last) / 60000)}m ago` : "empty (run: tracker sync)"
     });
-    const cachePath = resolve3(config.rootDir, config.cache.path);
+    const cachePath = resolve4(config.rootDir, config.cache.path);
     const gitRoot = findGitRoot(config.rootDir);
     if (gitRoot) {
       const ignored = isGitIgnored(gitRoot, cachePath);
@@ -1712,6 +1793,21 @@ all good.`);
   }
   return failed ? 1 : 0;
 }
+function cmdInit(args) {
+  const result = initProject(process.cwd(), {
+    baseUrl: str(args, "--base-url"),
+    project: str(args, "--project")
+  });
+  console.log(`created ${result.configPath}`);
+  for (const pattern of result.ignoreAdded)
+    console.log(`added "${pattern}" to .gitignore`);
+  for (const warning of result.warnings)
+    console.error(`warning: ${warning}`);
+  if (result.placeholders) {
+    console.log("next: edit gitlab.base_url and gitlab.project in the config");
+  }
+  console.log("then: export TRACKER_GITLAB_TOKEN (or add it to .env) and run: tracker doctor");
+}
 var VALUE_FLAGS = {
   ready: { "--parent": "value", "--json": "bool" },
   show: { "--json": "bool" },
@@ -1741,6 +1837,7 @@ var VALUE_FLAGS = {
   users: { "--json": "bool" },
   whoami: { "--json": "bool" },
   doctor: { "--json": "bool" },
+  init: { "--base-url": "value", "--project": "value" },
   memories: { "--json": "bool" },
   comment: {},
   comments: { "--json": "bool" },
@@ -1781,6 +1878,10 @@ ${HELP}`);
     return 0;
   }
   const args = parseArgs(rest, spec, ALIASES[cmd] ?? {});
+  if (cmd === "init") {
+    cmdInit(args);
+    return 0;
+  }
   if (cmd === "doctor")
     return cmdDoctor(args);
   const ctx = buildCtx();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackerctl",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Multi-backend issue-tracking CLI for humans and AI agents — claim races, dependencies, hierarchy, local FTS search, project memory. GitLab adapter first.",
   "license": "MIT",
   "author": "refo",