@formigio/fazemos-cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -6646,5 +6646,560 @@ ops
         process.exit(1);
     }
 });
+// ── F18 — Project-scoped docs surface ────────────────────────────────
+// Spec: specs/tech/platform/F18-project-scoped-docs-surface-tech-spec.md §8
+//
+// Five subcommands expose the Project docs tree + individual file reads
+// that F17 + F18 API ship. Active-Project-aware (F15): resolve active
+// Project from config; `--project <slug>` overrides. No active Project +
+// no override → exit 1 with the uniform "requirement missing: project"
+// block (matches handleScopedError + the F17 agents subcommands).
+//
+// Server-side F18 /docs/file currently returns a flat
+//   { path, file_type, content, sha, cached_at, etag }
+// envelope (see fazemos-api src/services/projectDocsService.ts). The tech
+// spec §4.2 also describes `frontmatter`, `body`, and `source` fields on
+// the response — those are Phase 3 web-surface additions not present in
+// the Phase 2 D2 API. The CLI renders the header line from the response's
+// `file_type` and the composed `<docs_root>/<path>` string (since the
+// source.path field doesn't exist yet on the wire). This is called out in
+// the handoff report as an API contract gap.
+//
+// Step-doc 422 handling (Phase 2 revision R2): when the server returns
+// 422 with code STEP_DOC_* and a `validation_errors` array, `docs cat`
+// prints the errors to stderr and exits 2 (distinct from the generic
+// error exit 1 so scripts can branch on "malformed doc" vs other failures).
+const docs = program.command('docs').description('Project docs browser. Read the Project-scoped tree and individual files that F18 exposes (Project agents, steps, and general docs) without opening the web UI.');
+/**
+ * F18 — resolve {orgId, projectId, projectSlug} for a docs subcommand.
+ * Mirrors F17's `requireProjectForAgents` but also surfaces the project
+ * slug for display purposes (header lines, GitHub URLs, local-path probe).
+ *
+ * On no-active-Project + no-override: emits the uniform F15 "requirement
+ * missing: project" block and exits 1. Reuses the wording from
+ * handleScopedError — the KD9 convention says the CLI always prints this
+ * as a triple-hint block (switch / --project / --all-projects), but
+ * --all-projects has no meaning for docs subcommands (each Project has
+ * its own docs tree — "all-projects" would be N API calls with no unified
+ * output). We omit the --all-projects hint here on purpose.
+ */
+async function requireProjectForDocs(slugOverride) {
+    const orgId = requireActiveOrgOrExit();
+    let projectId = null;
+    let projectSlug = null;
+    if (slugOverride) {
+        let project = findProjectBySlug(orgId, slugOverride);
+        if (!project) {
+            await refreshAuthMeCache();
+            project = findProjectBySlug(orgId, slugOverride);
+        }
+        if (!project) {
+            console.error(chalk.red(`Unknown project: ${slugOverride}`));
+            console.error(chalk.gray('Run: fazemos projects list'));
+            process.exit(1);
+        }
+        projectId = project.id;
+        projectSlug = project.slug;
+    }
+    else {
+        projectId = getActiveProjectId();
+        if (projectId) {
+            const proj = findProjectById(orgId, projectId);
+            projectSlug = proj?.slug ?? null;
+        }
+    }
+    if (!projectId) {
+        console.error(chalk.red('Error: requirement missing: project'));
+        console.error('');
+        console.error(chalk.gray('Set one with:  fazemos projects switch <slug>'));
+        console.error(chalk.gray('Or pass:       --project <slug>'));
+        process.exit(1);
+    }
+    // projectSlug can still be null if the cache is empty and we went the
+    // active-project path — refresh once so the smoke-test path of "I just
+    // authed in another shell" doesn't print UUIDs in headers.
+    if (!projectSlug) {
+        await refreshAuthMeCache();
+        const proj = findProjectById(orgId, projectId);
+        projectSlug = proj?.slug ?? projectId; // fall back to UUID if still unknown
+    }
+    return { orgId, projectId, projectSlug };
+}
+/**
+ * Render the `source` block as a short header label for `docs cat`.
+ * Tech spec §4.2 discriminator:
+ *   file                → "file"
+ *   file + level='org'  → "file (org)"
+ *   system_config       → "system config"
+ *   template            → "template"
+ * Falls back to "file" when the response pre-dates Phase 4b and omits
+ * the `source` block entirely (defensive — the API always ships it now).
+ */
+function renderOriginLabel(source) {
+    if (!source)
+        return 'file';
+    if (source.type === 'system_config')
+        return 'system config';
+    if (source.type === 'template')
+        return 'template';
+    if (source.level === 'org' || source.level === 'org_db')
+        return 'file (org)';
+    return 'file';
+}
+/**
+ * Fetch a Project's docs tree. Returns the raw payload. Swallows nothing —
+ * callers that want empty-state friendly output should branch on
+ * `payload.empty` + `payload.reason`.
+ */
+async function fetchDocsTree(orgId, projectId) {
+    return (await api('GET', `/api/organizations/${orgId}/projects/${projectId}/docs/tree`, undefined, { noProjectHeader: true }));
+}
+/**
+ * Render a flat list of tree entries as an indented text tree. The API
+ * returns paths with embedded slashes ("docs/product/fazemos-concept.md")
+ * and entries for both files and directories. We build a directory map
+ * from the entries and walk it alphabetically for stable output.
+ *
+ * Output format matches tech spec §8.2 — directory names end with `/`,
+ * files get 2-space indent per nesting level, and a file-type badge is
+ * appended for `agent` / `step` files (not `doc` — those are the default
+ * and badging every markdown file would be noisy). Size is NOT printed
+ * (noisy at list scale). Directory file-counts are computed locally.
+ */
+function renderDocsTree(entries) {
+    const root = { name: '', fullPath: '', isDir: true, children: new Map() };
+    function insert(path, entry, forceDir = false) {
+        const parts = path.split('/');
+        let cur = root;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            const isLast = i === parts.length - 1;
+            const isDir = !isLast || forceDir || entry?.type === 'dir';
+            let child = cur.children.get(part);
+            if (!child) {
+                child = {
+                    name: part,
+                    fullPath: parts.slice(0, i + 1).join('/'),
+                    isDir,
+                    children: new Map(),
+                };
+                cur.children.set(part, child);
+            }
+            if (isLast) {
+                child.entry = entry;
+                // Once marked as dir (by its own entry), don't downgrade.
+                if (isDir)
+                    child.isDir = true;
+            }
+            cur = child;
+        }
+    }
+    for (const e of entries) {
+        insert(e.path, e, e.type === 'dir');
+    }
+    function countFiles(node) {
+        if (!node.isDir)
+            return 1;
+        let n = 0;
+        for (const c of node.children.values())
+            n += countFiles(c);
+        return n;
+    }
+    const lines = [];
+    function walk(node, depth) {
+        const kids = Array.from(node.children.values()).sort((a, b) => {
+            // Directories first, then files, both alphabetical.
+            if (a.isDir !== b.isDir)
+                return a.isDir ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        for (const c of kids) {
+            const indent = '  '.repeat(depth);
+            if (c.isDir) {
+                const count = countFiles(c);
+                const tag = count ? chalk.gray(`  (${count} ${count === 1 ? 'file' : 'files'})`) : '';
+                lines.push(`${indent}${c.name}/${tag}`);
+                walk(c, depth + 1);
+            }
+            else {
+                const ft = c.entry?.file_type;
+                const badge = ft === 'agent'
+                    ? chalk.cyan(' [agent]')
+                    : ft === 'step'
+                        ? chalk.magenta(' [step]')
+                        : '';
+                lines.push(`${indent}${c.name}${badge}`);
+            }
+        }
+    }
+    walk(root, 0);
+    return lines;
+}
+/**
+ * Format the "Synced N ago" sub-header from a cached_at ISO string. Keep
+ * wording identical to UX §5.1 example ("Synced just now") when <30s.
+ */
+function formatSyncedLine(cachedAtIso) {
+    try {
+        const cached = new Date(cachedAtIso).getTime();
+        const now = Date.now();
+        const seconds = Math.max(0, Math.floor((now - cached) / 1000));
+        if (seconds < 30)
+            return 'Synced just now';
+        if (seconds < 90)
+            return 'Synced 1 minute ago';
+        if (seconds < 60 * 60)
+            return `Synced ${Math.floor(seconds / 60)} minutes ago`;
+        if (seconds < 2 * 60 * 60)
+            return 'Synced 1 hour ago';
+        return `Synced ${Math.floor(seconds / 3600)} hours ago`;
+    }
+    catch {
+        return `Synced at ${cachedAtIso}`;
+    }
+}
+// ── docs tree ────────────────────────────────────────────────────────
+docs
+    .command('tree')
+    .description('Show the Project\'s docs tree (agents/, steps/, docs/, plus the Project CLAUDE.md). Output is stable text suitable for piping.')
+    .option('--include-shared', 'Also print Org-shared docs (under `docs/` and root CLAUDE.md) as a second section', false)
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (opts) => {
+    try {
+        const { orgId, projectId, projectSlug } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        const repoBadge = payload.repo ? `${payload.repo} at ${payload.root ?? ''}` : '(no repo configured)';
+        console.log(chalk.cyan(`Docs — ${projectSlug} (${repoBadge})`));
+        console.log(chalk.gray(formatSyncedLine(payload.cached_at)));
+        console.log('');
+        if (payload.empty) {
+            if (payload.reason === 'no_docs_repo') {
+                console.log(chalk.yellow('No docs repository configured.'));
+                console.log(chalk.gray('  Set one with: fazemos projects update <slug> --docs-repo <owner/name> --docs-root <path>'));
+            }
+            else if (payload.reason === 'no_connection') {
+                console.log(chalk.yellow('Project has no active GitHub Connection.'));
+                console.log(chalk.gray('  Set one up with: fazemos connections ...'));
+            }
+            else {
+                console.log(chalk.yellow('Docs tree is empty.'));
+            }
+            return;
+        }
+        for (const line of renderDocsTree(payload.tree))
+            console.log(line);
+        if (opts.includeShared) {
+            console.log('');
+            console.log(chalk.gray('── Org shared ─────────────────────────────────────────'));
+            if (payload.org_shared && payload.org_shared.length) {
+                for (const line of renderDocsTree(payload.org_shared))
+                    console.log(line);
+            }
+            else {
+                // Phase 2 API does not yet populate org_shared (see the file-level
+                // note at the top of this block). Tell the operator what we see.
+                console.log(chalk.gray('(no org-shared docs returned by the API — Phase 2 ships Project-only)'));
+            }
+        }
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+// ── docs cat ─────────────────────────────────────────────────────────
+/**
+ * F18 §8 — step-doc validation failure exit code. Distinct from the
+ * generic error exit 1 so operator scripts can branch on "file is
+ * structurally invalid" vs "server 5xx / auth / other".
+ */
+const DOCS_STEP_VALIDATION_EXIT = 2;
+docs
+    .command('cat')
+    .description('Print a Project doc to stdout. Adds a one-line header showing the file type and source path. On malformed step docs, prints validation errors to stderr and exits 2.')
+    .argument('<path>', 'Relative path under docs_root (e.g., agents/marco.md, steps/feature-pipeline/tech-spec.md)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (relPath, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        // Phase 4b: the API now ships `source.path` on every /docs/file
+        // response (tech spec §4.2), so the Phase-3b tree pre-fetch that
+        // compensated for the missing field is gone. `source.path` is the
+        // authoritative repo-relative path. `tree` is only needed for the
+        // Org-shared fallback below (kept for resilience — if the server
+        // ever omits `source`, this still degrades to a helpful header).
+        let payload;
+        try {
+            payload = (await api('GET', `/api/organizations/${orgId}/projects/${projectId}/docs/file?path=${encodeURIComponent(relPath)}`, undefined, { noProjectHeader: true }));
+        }
+        catch (err) {
+            // Phase 2 revision R2: 422 on malformed step docs. The API
+            // returns `{ error, code: STEP_DOC_*, details: { path, validation_errors: [...] } }`.
+            if (err instanceof ApiError &&
+                err.status === 422 &&
+                typeof err.code === 'string' &&
+                err.code.startsWith('STEP_DOC_')) {
+                const body = (err.body ?? {});
+                console.error(chalk.red(`Error: ${err.message}`));
+                console.error(chalk.red(`  Code: ${err.code}`));
+                const ve = body.details?.validation_errors ?? [];
+                if (ve.length) {
+                    console.error(chalk.red('  Validation errors:'));
+                    for (const v of ve) {
+                        const field = v.field ? `${v.field}: ` : '';
+                        console.error(chalk.red(`    - ${field}${v.message ?? v.code ?? 'unknown'}`));
+                    }
+                }
+                process.exit(DOCS_STEP_VALIDATION_EXIT);
+            }
+            throw err;
+        }
+        // Header: file type + source discriminator + repo-relative path.
+        // Phase 4b: `source.path` / `source.type` / `source.level` are
+        // always present on a 200. The header reflects the §4.2 source
+        // block so an operator piping `docs cat` to a reviewer sees
+        // exactly where the bytes came from (file vs. system_config vs.
+        // template-inline).
+        const sourcePath = payload.source?.path ?? payload.path;
+        const typeLabel = payload.file_type === 'agent'
+            ? chalk.cyan('agent')
+            : payload.file_type === 'step'
+                ? chalk.magenta('step')
+                : chalk.gray('doc');
+        const originLabel = renderOriginLabel(payload.source);
+        console.log(chalk.gray(`# ${typeLabel} ${chalk.gray('·')} ${originLabel}: ${sourcePath}`));
+        console.log('');
+        if (payload.content == null) {
+            // DB-sourced response (system_config / template) per tech spec §4.2.
+            // content is null; the callable body is in `body` (Phase 3+).
+            if (payload.body) {
+                console.log(payload.body);
+            }
+            else {
+                console.log(chalk.gray('(no file content — this doc is sourced from system config / template inline; body field not yet exposed)'));
+            }
+            return;
+        }
+        // Trim trailing newlines; re-emit exactly one so `| grep` output
+        // doesn't end with multiple blank lines.
+        process.stdout.write(payload.content);
+        if (!payload.content.endsWith('\n'))
+            process.stdout.write('\n');
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+docs
+    .command('search')
+    .description('Search the Project docs tree by filename/path (case-insensitive). Phase 3: path-match only; server-side full-text search is deferred per spec §8.6.')
+    .argument('<query>', 'Substring to search for in file paths')
+    .option('--scope <scope>', 'Scope: this-project (default) | agents | steps | all', 'this-project')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (query, opts) => {
+    const scope = (opts.scope ?? 'this-project');
+    if (!['this-project', 'agents', 'steps', 'all'].includes(scope)) {
+        console.error(chalk.red(`Invalid --scope "${opts.scope}". Allowed: this-project, agents, steps, all`));
+        process.exit(1);
+    }
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        const pool = [];
+        for (const e of payload.tree)
+            if (e.type === 'file')
+                pool.push(e);
+        if (scope === 'all') {
+            for (const e of payload.org_shared ?? [])
+                if (e.type === 'file')
+                    pool.push(e);
+        }
+        const filtered = pool.filter((e) => {
+            if (scope === 'agents')
+                return e.file_type === 'agent';
+            if (scope === 'steps')
+                return e.file_type === 'step';
+            return true; // this-project | all
+        });
+        const q = query.toLowerCase();
+        const matches = filtered.filter((e) => e.path.toLowerCase().includes(q));
+        if (!matches.length) {
+            console.log(chalk.yellow(`No matches for "${query}" in scope "${scope}".`));
+            return;
+        }
+        // Highlight the matched substring. chalk.yellow the match so it's
+        // visible even in monochrome terminals (dim doesn't show well on
+        // light backgrounds).
+        for (const e of matches) {
+            const low = e.path.toLowerCase();
+            let out = '';
+            let i = 0;
+            while (i < e.path.length) {
+                const at = low.indexOf(q, i);
+                if (at < 0) {
+                    out += e.path.slice(i);
+                    break;
+                }
+                out += e.path.slice(i, at);
+                out += chalk.yellow(e.path.slice(at, at + q.length));
+                i = at + q.length;
+            }
+            const badge = e.file_type === 'agent'
+                ? chalk.cyan(' [agent]')
+                : e.file_type === 'step'
+                    ? chalk.magenta(' [step]')
+                    : '';
+            console.log(`  ${out}${badge}`);
+        }
+        console.log(chalk.gray(`\n${matches.length} ${matches.length === 1 ? 'match' : 'matches'} in scope "${scope}".`));
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+// ── docs path ────────────────────────────────────────────────────────
+/**
+ * F18 §8.5 — print the local workspace clone path for this Project,
+ * falling back to the GitHub URL when no local clone is detected.
+ *
+ * Local detection heuristic:
+ *   1. $FAZEMOS_WORKSPACE_PATH env var, if set + dir exists.
+ *   2. `~/development/<repo-name>/` (the Fazemos convention) + dir exists.
+ * If either matches, the full path is `<workspace>/<docs_root>`.
+ *
+ * When neither matches, we print the GitHub tree URL
+ * (https://github.com/<owner>/<repo>/tree/<branch>/<root>) so `open $(fazemos docs path)`
+ * on a fresh machine gracefully routes to the web UI instead of failing.
+ */
+docs
+    .command('path')
+    .description('Print the local filesystem path to this Project\'s docs root, or the GitHub URL if no local workspace clone is detected. Useful for `cd $(fazemos docs path)`.')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        if (!payload.repo) {
+            console.error(chalk.red('Project has no docs repository configured.'));
+            process.exit(1);
+        }
+        const repo = payload.repo;
+        const root = payload.root ?? '';
+        const branch = payload.branch ?? 'main';
+        // Local probe.
+        const candidates = [];
+        if (process.env.FAZEMOS_WORKSPACE_PATH)
+            candidates.push(process.env.FAZEMOS_WORKSPACE_PATH);
+        const home = process.env.HOME;
+        const repoName = repo.split('/').pop() ?? '';
+        if (home && repoName)
+            candidates.push(`${home}/development/${repoName}`);
+        for (const c of candidates) {
+            try {
+                if (existsSync(c) && statSync(c).isDirectory()) {
+                    // Emit to stdout only — the whole point is that `cd $(fazemos docs path)` works.
+                    console.log(root ? `${c}/${root}` : c);
+                    return;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        // No local clone — print the GitHub URL.
+        const url = root
+            ? `https://github.com/${repo}/tree/${branch}/${root}`
+            : `https://github.com/${repo}/tree/${branch}`;
+        console.log(url);
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
+// ── docs open ────────────────────────────────────────────────────────
+/**
+ * F18 §8 — open a doc. If the workspace repo is cloned locally AND we're
+ * currently inside that clone (heuristic: cwd's git-root has a remote
+ * matching the Project's configured docs_repo), launch $EDITOR. Otherwise
+ * print the GitHub blob URL so operators on a fresh machine get a sensible
+ * fallback.
+ *
+ * Why the "cwd is the git clone" heuristic rather than just "any clone
+ * exists anywhere on disk"? Operators routinely run the CLI from inside
+ * workspace shells (that's where the Fazemos CLI lives in the workflow)
+ * and expect `fazemos docs open` to touch the same clone they're editing.
+ * If they're in a different shell, opening GitHub in a browser is the
+ * safer action than editing a clone they didn't ask about.
+ */
+docs
+    .command('open')
+    .description('Open a Project doc. If you\'re inside the workspace repo clone, launches $EDITOR on the file; otherwise prints the GitHub blob URL.')
+    .argument('<path>', 'Relative path under docs_root (e.g., agents/marco.md)')
+    .option('--project <slug>', 'Override active Project for this call')
+    .action(async (relPath, opts) => {
+    try {
+        const { orgId, projectId } = await requireProjectForDocs(opts.project);
+        const payload = await fetchDocsTree(orgId, projectId);
+        if (!payload.repo) {
+            console.error(chalk.red('Project has no docs repository configured.'));
+            process.exit(1);
+        }
+        const repo = payload.repo;
+        const root = payload.root ?? '';
+        const branch = payload.branch ?? 'main';
+        // Heuristic: are we inside a git clone whose origin matches `repo`?
+        let localWorkspacePath = null;
+        try {
+            const gitRoot = execSync('git rev-parse --show-toplevel', {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (gitRoot) {
+                const originUrl = execSync('git config --get remote.origin.url', {
+                    encoding: 'utf-8',
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                    cwd: gitRoot,
+                }).trim();
+                // Accept any URL form that ends with the repo's `owner/name`
+                // (with optional `.git` suffix). Covers https, ssh, and git://.
+                const re = new RegExp(`[:/]${repo.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}(?:\\.git)?$`);
+                if (re.test(originUrl)) {
+                    localWorkspacePath = gitRoot;
+                }
+            }
+        }
+        catch {
+            // Not a git repo, or git not available — fall through to URL.
+        }
+        if (localWorkspacePath) {
+            const fullPath = root
+                ? `${localWorkspacePath}/${root}/${relPath}`
+                : `${localWorkspacePath}/${relPath}`;
+            const editor = process.env.EDITOR || process.env.VISUAL;
+            if (!editor) {
+                console.error(chalk.red('No $EDITOR or $VISUAL configured. Set one (e.g., `export EDITOR=code`) or re-run from outside the workspace clone to get the GitHub URL.'));
+                // Still print the full local path so the operator can open it manually.
+                console.log(fullPath);
+                process.exit(1);
+            }
+            try {
+                execSync(`${editor} "${fullPath}"`, { stdio: 'inherit' });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(chalk.red(`Failed to launch editor: ${msg}`));
+                process.exit(1);
+            }
+            return;
+        }
+        // Not inside the workspace clone — print the GitHub blob URL.
+        const url = root
+            ? `https://github.com/${repo}/blob/${branch}/${root}/${relPath}`
+            : `https://github.com/${repo}/blob/${branch}/${relPath}`;
+        console.log(url);
+    }
+    catch (err) {
+        handleScopedError(err);
+    }
+});
 program.parse();
 //# sourceMappingURL=index.js.map