felenova-backlog 0.1.0

package/dist/config.js

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** The committed, token-free project file (DECISION-026). */
+export const CONFIG_FILENAME = 'backlog.config.json';
+/** A refusal about the config file itself: always names the file and the offending key. */
+export class ConfigError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.name = 'ConfigError';
+        this.path = path;
+    }
+}
+const REQUIRED_KEYS = ['url', 'project', 'conductor_dir'];
+/**
+ * Anything that could hold a credential is a hard error, not a warning: this file is
+ * committed, and `no secret in a tracked file` is a hard rule. The name alone is enough —
+ * we never look at the value, so nothing here can echo one.
+ */
+const CREDENTIAL_KEY = /token|secret|key|password|credential/i;
+/** Walks up from `cwd` looking for `backlog.config.json`. Returns its path, or null. */
+export function findConfig(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const candidate = join(dir, CONFIG_FILENAME);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function validate(path, raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new ConfigError(path, `${CONFIG_FILENAME} must contain a JSON object`);
+    }
+    const doc = raw;
+    for (const key of Object.keys(doc)) {
+        if (CREDENTIAL_KEY.test(key)) {
+            throw new ConfigError(path, `${CONFIG_FILENAME} has a key that could hold a credential: "${key}" — this file is committed and must never carry a token; keep the PAT in ~/.config/backlog/token or $BACKLOG_TOKEN`);
+        }
+        if (!REQUIRED_KEYS.includes(key)) {
+            throw new ConfigError(path, `${CONFIG_FILENAME} has an unknown key: "${key}" — only ${REQUIRED_KEYS.join(', ')} are allowed`);
+        }
+    }
+    for (const key of REQUIRED_KEYS) {
+        const value = doc[key];
+        if (value === undefined) {
+            throw new ConfigError(path, `${CONFIG_FILENAME} is missing "${key}"`);
+        }
+        if (typeof value !== 'string') {
+            throw new ConfigError(path, `${CONFIG_FILENAME} key "${key}" must be a string`);
+        }
+        if (value.trim() === '') {
+            throw new ConfigError(path, `${CONFIG_FILENAME} key "${key}" must not be empty`);
+        }
+    }
+    const url = doc.url.trim();
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new ConfigError(path, `${CONFIG_FILENAME} key "url" is not a URL: ${url}`);
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new ConfigError(path, `${CONFIG_FILENAME} key "url" must be http(s), not ${parsed.protocol}`);
+    }
+    return {
+        url: url.replace(/\/+$/, ''),
+        project: doc.project.trim(),
+        conductor_dir: doc.conductor_dir.trim(),
+    };
+}
+/** Reads and validates one config file. Throws `ConfigError` on anything but the exact shape. */
+export function readConfig(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        throw new ConfigError(path, `cannot read ${CONFIG_FILENAME} at ${path}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ConfigError(path, `${CONFIG_FILENAME} at ${path} is not valid JSON`);
+    }
+    return validate(path, raw);
+}
+/** Walk-up + read. Null when no config exists above `cwd`; throws when one exists but is bad. */
+export function loadConfig(cwd) {
+    const path = findConfig(cwd);
+    if (!path)
+        return null;
+    return { config: readConfig(path), path };
+}
+/** Writes the three keys, validated first so a bad object can never reach a tracked file. */
+export function writeConfig(path, config) {
+    const clean = validate(path, config);
+    const body = {
+        url: clean.url,
+        project: clean.project,
+        conductor_dir: clean.conductor_dir,
+    };
+    writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+}
+/**
+ * Precedence for every command: `--url`/`--project` → `BACKLOG_URL`/`BACKLOG_PROJECT` →
+ * the config file → a refusal pointing at `backlog init`. Resolved per field, so a flag
+ * can name a project while the URL still comes from the committed file.
+ */
+export function resolveTarget(flags, env, cwd) {
+    const loaded = loadConfig(cwd);
+    const project = flags.project?.trim() || env.BACKLOG_PROJECT?.trim() || loaded?.config.project;
+    const url = flags.url?.trim() || env.BACKLOG_URL?.trim() || loaded?.config.url;
+    if (!project)
+        throw new Error('no project configured — run: backlog init');
+    if (!url)
+        throw new Error('no service URL configured — run: backlog init');
+    const source = flags.project?.trim()
+        ? 'flag'
+        : env.BACKLOG_PROJECT?.trim()
+            ? 'env'
+            : 'config';
+    return {
+        url: url.replace(/\/+$/, ''),
+        project,
+        conductor_dir: loaded?.config.conductor_dir ?? 'conductor',
+        source,
+        configPath: loaded?.path ?? null,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,eAAe,GAAG,qBAAqB,CAAC;AAkBrD,2FAA2F;AAC3F,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,eAAe,CAAU,CAAC;AAEnE;;;;GAIG;AACH,MAAM,cAAc,GAAG,uCAAuC,CAAC;AAE/D,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACvB,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;QAC7C,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,GAAY;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,eAAe,6BAA6B,CAAC,CAAC;IAC/E,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAE3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,WAAW,CACnB,IAAI,EACJ,GAAG,eAAe,6CAA6C,GAAG,oHAAoH,CACvL,CAAC;QACJ,CAAC;QACD,IAAI,CAAE,aAAmC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,WAAW,CACnB,IAAI,EACJ,GAAG,eAAe,yBAAyB,GAAG,YAAY,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CACjG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,eAAe,gBAAgB,GAAG,GAAG,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,eAAe,SAAS,GAAG,oBAAoB,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,eAAe,SAAS,GAAG,qBAAqB,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAI,GAAG,CAAC,GAAc,CAAC,IAAI,EAAE,CAAC;IACvC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,eAAe,4BAA4B,GAAG,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,WAAW,CACnB,IAAI,EACJ,GAAG,eAAe,mCAAmC,MAAM,CAAC,QAAQ,EAAE,CACvE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,OAAO,EAAG,GAAG,CAAC,OAAkB,CAAC,IAAI,EAAE;QACvC,aAAa,EAAG,GAAG,CAAC,aAAwB,CAAC,IAAI,EAAE;KACpD,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,eAAe,eAAe,OAAO,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,eAAe,OAAO,IAAI,oBAAoB,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAAqB;IAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG;QACX,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,aAAa,EAAE,KAAK,CAAC,aAAa;KACnC,CAAC;IACF,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC;AAgBD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAkB,EAClB,GAAsB,EACtB,GAAW;IAEX,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAE/B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;IAC/F,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;IAE/E,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC3E,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAE3E,MAAM,MAAM,GAA6B,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;QAC5D,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE;YAC3B,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,QAAQ,CAAC;IAEf,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,OAAO;QACP,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,IAAI,WAAW;QAC1D,MAAM;QACN,UAAU,EAAE,MAAM,EAAE,IAAI,IAAI,IAAI;KACjC,CAAC;AACJ,CAAC"}

package/dist/doctor.d.ts

@@ -0,0 +1,28 @@
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    hint?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+/**
+ * Every file `init` installs for the plugin, relative to the repo root. The list is the
+ * payload's own — one source of truth, so a file added to the payload is a file the doctor
+ * starts checking for.
+ */
+export declare const PLUGIN_INSTALL_TARGETS: readonly string[];
+/** Local-only checks: the token store, the tracked-file scan, and the four local artifacts. */
+export declare function runDoctor(env: NodeJS.ProcessEnv, opts?: {
+    cwd?: string;
+    home?: string;
+}): DoctorReport;
+/** Local checks plus the remote `project_visible` check. Service reachability comes from here. */
+export declare function runDoctorRemote(env: NodeJS.ProcessEnv, opts?: {
+    cwd?: string;
+    home?: string;
+    url?: string;
+    project?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<DoctorReport>;

package/dist/doctor.js

@@ -0,0 +1,377 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ApiError } from './api.js';
+import { CONFIG_FILENAME, ConfigError, loadConfig } from './config.js';
+import { explain } from './errors.js';
+import { PLUGIN_NAME, PLUGIN_PAYLOAD } from './init/plugin.js';
+import { MCP_SERVER_KEY, TOKEN_PLACEHOLDER as TEMPLATE_TOKEN_PLACEHOLDER, } from './init/templates.js';
+const MAX_SCAN_BYTES = 2 * 1024 * 1024;
+// Patterns are inert regex source, never live-looking literals, so this file itself
+// stays clean under the same scan it implements (and under gitleaks' backlog-pat rule).
+const LITERAL_TOKEN_PATTERNS = [/bkl_[A-Za-z0-9]{40}/, /sb_secret_[A-Za-z0-9_-]{20,}/];
+/** `~/.config/backlog/token` presence + permissions, when no BACKLOG_TOKEN is set in the env. */
+function checkTokenFile(env, home) {
+    const path = join(home, '.config', 'backlog', 'token');
+    if (process.platform === 'win32') {
+        return {
+            name: 'token_file',
+            ok: true,
+            hint: `POSIX file-mode checks are skipped on ${process.platform}; token file would be ${path}`,
+        };
+    }
+    if (env.BACKLOG_TOKEN) {
+        return {
+            name: 'token_file',
+            ok: true,
+            hint: `BACKLOG_TOKEN is set from the environment; ${path} is not required`,
+        };
+    }
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        return {
+            name: 'token_file',
+            ok: false,
+            hint: `no BACKLOG_TOKEN and ${path} does not exist — set BACKLOG_TOKEN or write your PAT there (chmod 600)`,
+        };
+    }
+    const mode = stat.mode & 0o777;
+    if (mode !== 0o600) {
+        return {
+            name: 'token_file',
+            ok: false,
+            hint: `${path} must be mode 600 (found ${mode.toString(8)}) — run: chmod 600 ${path}`,
+        };
+    }
+    return { name: 'token_file', ok: true };
+}
+/** Scans every git-tracked file in `cwd` for a literal `bkl_…` or `sb_secret_…` pattern. */
+function checkNoLiteralToken(cwd) {
+    let files;
+    try {
+        const out = execFileSync('git', ['-C', cwd, 'ls-files', '-z'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        files = out.split('\0').filter(Boolean);
+    }
+    catch {
+        return {
+            name: 'no_literal_token',
+            ok: true,
+            hint: `${cwd} is not a git repository — skipped`,
+        };
+    }
+    const findings = [];
+    for (const file of files) {
+        const abs = join(cwd, file);
+        let stat;
+        try {
+            stat = statSync(abs);
+        }
+        catch {
+            continue; // tracked but missing on disk (e.g. a submodule pointer)
+        }
+        if (!stat.isFile() || stat.size > MAX_SCAN_BYTES)
+            continue;
+        let content;
+        try {
+            content = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue; // unreadable/binary
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (LITERAL_TOKEN_PATTERNS.some((pattern) => pattern.test(lines[i]))) {
+                findings.push(`${file}:${i + 1}`);
+            }
+        }
+    }
+    if (findings.length > 0) {
+        return {
+            name: 'no_literal_token',
+            ok: false,
+            hint: `literal token pattern found in: ${findings.join(', ')}`,
+        };
+    }
+    return { name: 'no_literal_token', ok: true };
+}
+/**
+ * Every file `init` installs for the plugin, relative to the repo root. The list is the
+ * payload's own — one source of truth, so a file added to the payload is a file the doctor
+ * starts checking for.
+ */
+export const PLUGIN_INSTALL_TARGETS = PLUGIN_PAYLOAD.map((f) => f.target);
+/** The three files a usable `conductor/` always has (PRODUCT-SPEC §7.3). */
+const CONDUCTOR_FILES = ['workflow.md', 'tracks.md', 'index.md'];
+/** The literal `.mcp.json` must carry — never a token value. `templates.ts` owns it. */
+const TOKEN_PLACEHOLDER = TEMPLATE_TOKEN_PLACEHOLDER;
+/** One walk-up per doctor run, shared by the `config`, `conductor_dir` and remote checks. */
+function resolveConfig(cwd) {
+    try {
+        const loaded = loadConfig(cwd);
+        if (!loaded)
+            return { config: null, path: null, error: null };
+        return { config: loaded.config, path: loaded.path, error: null };
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            return { config: null, path: err.path, error: err.message };
+        return {
+            config: null,
+            path: null,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** `backlog.config.json` found, valid, and what it says. */
+function checkConfig(resolved) {
+    if (resolved.error) {
+        return { name: 'config', ok: false, hint: resolved.error };
+    }
+    if (!resolved.config || !resolved.path) {
+        return {
+            name: 'config',
+            ok: false,
+            hint: `no ${CONFIG_FILENAME} found here or in any parent directory — run: backlog init`,
+        };
+    }
+    return {
+        name: 'config',
+        ok: true,
+        hint: `${resolved.path}: url ${resolved.config.url}, project ${resolved.config.project}`,
+    };
+}
+/** The conductor directory: present with its scaffold, or not there yet. */
+function checkConductorDir(cwd, resolved) {
+    const rel = resolved.config?.conductor_dir ?? 'conductor';
+    const dir = join(cwd, rel);
+    if (!existsSync(dir)) {
+        return {
+            name: 'conductor_dir',
+            ok: true,
+            hint: `${rel}/ does not exist — it will be created by init`,
+        };
+    }
+    const missing = CONDUCTOR_FILES.filter((f) => !existsSync(join(dir, f)));
+    if (missing.length > 0) {
+        return {
+            name: 'conductor_dir',
+            ok: false,
+            hint: `${rel}/ exists but is missing ${missing.join(', ')} — run: backlog init (it adds only the files that are absent)`,
+        };
+    }
+    return { name: 'conductor_dir', ok: true, hint: `${rel}/ has ${CONDUCTOR_FILES.join(', ')}` };
+}
+/** `.mcp.json` references the placeholder and carries no token value. */
+function checkMcpEntry(cwd) {
+    const path = join(cwd, '.mcp.json');
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return {
+            name: 'mcp_entry',
+            ok: false,
+            hint: `no .mcp.json in ${cwd} — run: backlog init (it writes the ${MCP_SERVER_KEY} server entry referencing ${TOKEN_PLACEHOLDER})`,
+        };
+    }
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        return { name: 'mcp_entry', ok: false, hint: `.mcp.json is not valid JSON` };
+    }
+    const servers = doc?.mcpServers;
+    if (typeof servers !== 'object' || servers === null) {
+        return { name: 'mcp_entry', ok: false, hint: '.mcp.json has no mcpServers object' };
+    }
+    const entry = servers[MCP_SERVER_KEY];
+    if (entry === undefined) {
+        return {
+            name: 'mcp_entry',
+            ok: false,
+            hint: `.mcp.json has no "${MCP_SERVER_KEY}" server entry — run: backlog init`,
+        };
+    }
+    const serialised = JSON.stringify(entry);
+    if (LITERAL_TOKEN_PATTERNS.some((pattern) => pattern.test(serialised))) {
+        return {
+            name: 'mcp_entry',
+            ok: false,
+            hint: `.mcp.json's ${MCP_SERVER_KEY} entry carries a literal token — replace it with ${TOKEN_PLACEHOLDER} and revoke that PAT`,
+        };
+    }
+    if (!serialised.includes(TOKEN_PLACEHOLDER)) {
+        return {
+            name: 'mcp_entry',
+            ok: false,
+            hint: `.mcp.json's ${MCP_SERVER_KEY} entry does not reference ${TOKEN_PLACEHOLDER} — the token must come from the environment, never the file`,
+        };
+    }
+    return { name: 'mcp_entry', ok: true, hint: `.mcp.json references ${TOKEN_PLACEHOLDER}` };
+}
+/**
+ * The plugin payload, file by file. The skills live in `.claude/skills/` and the commands in
+ * `.claude/commands/backlog/` because that is the only layout a repo-installed payload
+ * actually loads from (see `init/plugin.ts` for what was verified and how).
+ */
+function checkPluginInstalled(cwd) {
+    const missing = PLUGIN_INSTALL_TARGETS.filter((rel) => !existsSync(join(cwd, rel)));
+    if (missing.length > 0) {
+        return {
+            name: 'plugin_installed',
+            ok: false,
+            hint: `missing ${missing.join(', ')} — run: backlog init to install the ${PLUGIN_NAME} plugin`,
+        };
+    }
+    return {
+        name: 'plugin_installed',
+        ok: true,
+        hint: `${PLUGIN_NAME}: ${PLUGIN_INSTALL_TARGETS.length} skill and command files installed`,
+    };
+}
+/** Local-only checks: the token store, the tracked-file scan, and the four local artifacts. */
+export function runDoctor(env, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const resolved = resolveConfig(cwd);
+    const checks = [
+        {
+            name: 'token',
+            ok: Boolean(env.BACKLOG_TOKEN),
+            hint: 'set BACKLOG_TOKEN (PAT from the web UI; stored at ~/.config/backlog/token)',
+        },
+        checkTokenFile(env, home),
+        checkNoLiteralToken(cwd),
+        checkConfig(resolved),
+        checkConductorDir(cwd, resolved),
+        checkMcpEntry(cwd),
+        checkPluginInstalled(cwd),
+    ];
+    return { ok: checks.every((c) => c.ok), checks };
+}
+/**
+ * The configured project/URL come from `--project`/`--url`, then
+ * `BACKLOG_PROJECT`/`BACKLOG_URL`, then `backlog.config.json` (PLG-001) — the same
+ * precedence every command uses (`config.resolveTarget`). The flag still wins.
+ *
+ * The token stays env-only here on purpose: reading `~/.config/backlog/token` from a
+ * diagnostic would make `doctor` touch a live credential it does not need. `token_file`
+ * already reports on that file.
+ */
+async function checkProjectVisible(env, opts) {
+    const project = opts.project ?? env.BACKLOG_PROJECT ?? opts.config?.project;
+    if (!project) {
+        return {
+            name: 'project_visible',
+            ok: true,
+            hint: 'no project configured (set BACKLOG_PROJECT or pass --project); skipping the visibility check',
+        };
+    }
+    const token = env.BACKLOG_TOKEN;
+    const url = opts.url ?? env.BACKLOG_URL ?? opts.config?.url;
+    if (!token && !url) {
+        return {
+            name: 'project_visible',
+            ok: true,
+            hint: 'cannot check project visibility: BACKLOG_TOKEN and BACKLOG_URL (or --url) are not set',
+        };
+    }
+    if (!token) {
+        return {
+            name: 'project_visible',
+            ok: true,
+            hint: 'cannot check project visibility: BACKLOG_TOKEN is not set',
+        };
+    }
+    if (!url) {
+        return {
+            name: 'project_visible',
+            ok: true,
+            hint: 'cannot check project visibility: BACKLOG_URL (or --url) is not set',
+        };
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await fetchImpl(`${url}/v1/projects`, {
+            headers: { Authorization: `Bearer ${token}`, accept: 'application/json' },
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { name: 'project_visible', ok: false, hint: `could not reach ${url}: ${message}` };
+    }
+    if (response.status === 401 || response.status === 403) {
+        return {
+            name: 'project_visible',
+            ok: false,
+            hint: `the token was rejected by ${url} (HTTP ${response.status}) — mint a new PAT at ${url}/me`,
+        };
+    }
+    if (response.status !== 200) {
+        return {
+            name: 'project_visible',
+            ok: false,
+            hint: `${url} answered HTTP ${response.status} for /v1/projects`,
+        };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return {
+            name: 'project_visible',
+            ok: false,
+            hint: `${url} returned a malformed response for /v1/projects`,
+        };
+    }
+    if (!Array.isArray(body)) {
+        return {
+            name: 'project_visible',
+            ok: false,
+            hint: `${url} returned a malformed response for /v1/projects`,
+        };
+    }
+    const projects = body;
+    const match = projects.find((p) => p.slug === project);
+    if (match) {
+        const roleClause = match.role ? ` as ${match.role}` : '';
+        return {
+            name: 'project_visible',
+            ok: true,
+            hint: `project ${project} is visible to this token${roleClause}`,
+        };
+    }
+    const visibleSlugs = projects.map((p) => p.slug).filter((s) => Boolean(s));
+    const visibleClause = visibleSlugs.length > 0 ? ` (visible: ${visibleSlugs.join(', ')})` : '';
+    // The same sentence every command prints for this case, so `doctor` and `status` agree:
+    // the service answers `not_found` for a project the caller has no role on, by design.
+    const sentence = explain(new ApiError(404, 'not_found', ''), { project, url });
+    return {
+        name: 'project_visible',
+        ok: false,
+        hint: `${sentence}; the token may also be pinned to another project${visibleClause}`,
+    };
+}
+/** Local checks plus the remote `project_visible` check. Service reachability comes from here. */
+export async function runDoctorRemote(env, opts = {}) {
+    const local = runDoctor(env, opts);
+    const cwd = opts.cwd ?? process.cwd();
+    const remoteCheck = await checkProjectVisible(env, {
+        ...opts,
+        config: resolveConfig(cwd).config,
+    });
+    const checks = [...local.checks, remoteCheck];
+    return { ok: checks.every((c) => c.ok), checks };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+import type { ApiError } from './api.js';
+/**
+ * One human sentence per refusal — never JSON, never a status code, never a stack.
+ * Every code `apps/service` can answer has a row here; `src/errors.test.ts` enumerates the
+ * shipped list, so a new service code fails the CLI build until it gets a sentence.
+ */
+export interface ErrorContext {
+    /** The configured project — what makes a `not_found` a membership problem. */
+    project?: string | undefined;
+    /** The service URL, for the rows that tell the reader where to go. */
+    url?: string | undefined;
+    /** The command being run, for the rows that can name it. */
+    command?: string | undefined;
+    /** An item/track ref, when the command had one. */
+    ref?: string | undefined;
+}
+/** Every code with a row, in the order the table below reads. */
+export declare const ERROR_CODES: readonly ["unreachable", "forbidden", "not_found", "locked", "not_locked", "invalid_transition", "reason_required", "invalid_request", "conflict", "superseded", "internal", "no_session", "token_required", "token_unknown", "token_revoked", "token_expired", "no_member", "rate_limited", "read_only_token", "session_required"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+/** The code → sentence table. Exactly one line, always. */
+export declare function explain(err: ApiError, ctx?: ErrorContext): string;
+/** The plan's name for `explain`. */
+export declare function renderError(err: ApiError, ctx?: ErrorContext): string;