@4ge/cli 0.1.0

package/dist/core/config/parser.js

@@ -0,0 +1,213 @@
+import { mkdir, readFile, writeFile, stat, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse, stringify } from 'yaml';
+import { ProjectConfigSchema } from './schema.js';
+/**
+ * Path to local .4ge directory
+ */
+export function getLocal4geDir() {
+    return join(process.cwd(), '.4ge');
+}
+/**
+ * Check if .4ge directory exists
+ */
+export async function hasLocal4geDir() {
+    try {
+        const s = await stat(getLocal4geDir());
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Path to local project config.
+ * Config lives at the .4ge root — root is reserved for config + secrets.
+ */
+export function getLocalConfigPath() {
+    return join(getLocal4geDir(), 'config.yaml');
+}
+/**
+ * Path to the assets subdirectory.
+ *
+ * Pulled / cached items (project.json, plan.json, template.json,
+ * stories/, epics/, features/, project/*.md) live under here, keeping the
+ * .4ge root clean for config + secrets.
+ */
+export function getAssetsDir() {
+    return join(getLocal4geDir(), 'assets');
+}
+/**
+ * Resolve an asset path under .4ge/assets.
+ *
+ * Works for both singleton files (e.g. 'project.json') and collection
+ * directories (e.g. 'stories'). Caller joins further path segments as needed.
+ */
+export function getAssetPath(name) {
+    return join(getAssetsDir(), name);
+}
+/**
+ * Path to a collection directory under .4ge/assets (e.g. 'stories', 'epics').
+ *
+ * Semantically distinct from getAssetPath() for singletons — signals that the
+ * caller will join further segments (typically per-id files) under this dir.
+ */
+export function getCollectionDir(name) {
+    return join(getAssetsDir(), name);
+}
+/**
+ * Path to the pulled project markdown docs directory (.4ge/assets/project).
+ */
+export function getProjectDocsDir() {
+    return join(getAssetsDir(), 'project');
+}
+/**
+ * Read and validate project configuration from .4ge/config.yaml.
+ * Returns null if the file is missing, empty, invalid YAML, or fails schema validation.
+ * Guaranteed not to throw.
+ */
+export async function readConfig() {
+    try {
+        const content = await readFile(getLocalConfigPath(), 'utf-8');
+        if (!content.trim())
+            return null;
+        const data = parse(content);
+        const result = ProjectConfigSchema.safeParse(data);
+        return result.success ? result.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeConfig(config) {
+    await mkdir(getLocal4geDir(), { recursive: true, mode: 0o700 });
+    const yamlContent = stringify(config, { indent: 2, aliasDuplicateObjects: false });
+    await writeFile(getLocalConfigPath(), yamlContent, 'utf-8');
+}
+/**
+ * Update project configuration with partial values.
+ * Deeply merges hierarchy, pull, and cli sections.
+ * @throws Error if config file is not found or validation fails.
+ */
+export async function updateConfig(updates) {
+    const current = await readConfig();
+    if (!current) {
+        throw new Error('No project config found. Run `4ge init` first.');
+    }
+    const merged = {
+        ...current,
+        ...updates,
+        hierarchy: { ...current.hierarchy, ...updates.hierarchy },
+        pull: { ...current.pull, ...updates.pull },
+        cli: { ...current.cli, ...updates.cli },
+    };
+    const validated = ProjectConfigSchema.parse(merged);
+    await writeConfig(validated);
+    return validated;
+}
+export async function isProjectInitialized() {
+    const config = await readConfig();
+    return Boolean(config?.project_id && config?.workspace_id);
+}
+/**
+ * Asset entries that previously lived at the .4ge root and must be moved
+ * under .4ge/assets/ during one-time migration.
+ */
+const LEGACY_ASSET_FILES = ['project.json', 'plan.json', 'template.json'];
+const LEGACY_ASSET_DIRS = ['project', 'stories', 'epics', 'features'];
+/**
+ * One-time, idempotent migration of legacy root-level assets into .4ge/assets/.
+ *
+ * Moves singletons (project.json, plan.json, template.json) and collection
+ * directories (project/, stories/, epics/, features/) that used to sit directly
+ * under .4ge/ into .4ge/assets/. Config and secrets at the root are never touched.
+ *
+ * If an asset already exists at the destination it is skipped (never overwritten),
+ * so re-runs are safe and never clobber newer pulls.
+ */
+export async function migrateLegacyAssets(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const root = join(cwd, '.4ge');
+    const assetsDir = join(root, 'assets');
+    const moved = [];
+    const skipped = [];
+    // Bail fast if .4ge was never initialised.
+    try {
+        if (!(await stat(root)).isDirectory())
+            return { moved, skipped };
+    }
+    catch {
+        return { moved, skipped };
+    }
+    await mkdir(assetsDir, { recursive: true });
+    for (const name of LEGACY_ASSET_FILES) {
+        const src = join(root, name);
+        const dest = join(assetsDir, name);
+        let srcStat;
+        try {
+            srcStat = await stat(src);
+        }
+        catch {
+            continue;
+        }
+        if (!srcStat.isFile())
+            continue;
+        try {
+            await stat(dest);
+            skipped.push(name);
+            continue;
+        }
+        catch {
+            // dest missing — proceed
+        }
+        await writeFile(dest, await readFile(src, 'utf-8'), 'utf-8');
+        await rm(src);
+        moved.push(name);
+    }
+    for (const name of LEGACY_ASSET_DIRS) {
+        const src = join(root, name);
+        const dest = join(assetsDir, name);
+        let srcStat;
+        try {
+            srcStat = await stat(src);
+        }
+        catch {
+            continue;
+        }
+        if (!srcStat.isDirectory())
+            continue;
+        // Skip entirely if destination already exists — never merge over a newer pull.
+        try {
+            await stat(dest);
+            skipped.push(`${name}/`);
+            continue;
+        }
+        catch {
+            // dest missing — proceed
+        }
+        await moveDir(src, dest);
+        moved.push(`${name}/`);
+    }
+    return { moved, skipped };
+}
+async function moveDir(src, dest) {
+    await mkdir(dest, { recursive: true });
+    for (const entry of await readdir(src, { withFileTypes: true })) {
+        const from = join(src, entry.name);
+        const to = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await moveDir(from, to);
+        }
+        else {
+            await writeFile(to, await readFile(from, 'utf-8'), 'utf-8');
+        }
+    }
+    await rm(src, { recursive: true, force: true });
+}
+/**
+ * Generate .gitignore entries for .4ge/ sensitive files.
+ * Paths are relative to the .4ge/ directory.
+ */
+export function getGitignoreEntries() {
+    return ['credentials.json', '.env'];
+}

package/dist/core/config/schema.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+// Config schema for .4ge/config.yaml
+export const ProjectConfigSchema = z.object({
+    project_id: z.string().uuid(),
+    workspace_id: z.string().uuid(),
+    project_name: z.string().optional(),
+    workspace_name: z.string().optional(),
+    hierarchy: z.object({
+        default_roadmap_filter: z.enum(['now', 'next', 'later', 'all']).default('now'),
+        recursive_pull: z.boolean().default(true),
+    }).default({
+        default_roadmap_filter: 'now',
+        recursive_pull: true,
+    }),
+    pull: z.object({
+        generate_stubs: z.boolean().default(false),
+        include_brief_deps: z.boolean().default(false),
+    }).default({
+        generate_stubs: false,
+        include_brief_deps: false,
+    }),
+    cli: z.object({
+        default_mode: z.enum(['pretty', 'interactive']).default('pretty'),
+    }).default({
+        default_mode: 'pretty',
+    }),
+});
+// Partial config for init (some fields may not be set yet)
+export const PartialProjectConfigSchema = ProjectConfigSchema.partial();

package/dist/core/project/markdown.js

@@ -0,0 +1,37 @@
+export function generateProblemStatementMd(project) {
+    const content = project.problem_statement?.trim();
+    if (!content)
+        return null;
+    return `# ${project.name} — Problem Statement
+
+${content}`;
+}
+export function generateProjectRulesMd(project) {
+    const content = project.project_rules?.trim();
+    if (!content)
+        return null;
+    return `# ${project.name} — Project Rules
+
+${content}`;
+}
+export function generateReadmeMd(project, filesGenerated) {
+    const description = project.description?.trim() || 'No description';
+    const fileLinks = filesGenerated
+        .map((file) => `- [${file}](./${file})`)
+        .join('\n');
+    const date = new Date().toISOString();
+    return `# ${project.name}
+
+> ${description}
+
+**Status:** ${project.status}
+**Project ID:** ${project.id}
+**Workspace:** ${project.workspace_id}
+
+## Local Reference Files
+
+${fileLinks}
+
+---
+*Generated by \`4ge project pull\` on ${date}*`;
+}

package/dist/core/skill/installer.js

@@ -0,0 +1,59 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { resolveSkillPath } from './paths.js';
+/**
+ * Location of the canonical skill content, bundled with the package.
+ *
+ * Resolves relative to this compiled module:
+ * - prod:  dist/core/skill/installer.js -> ../../skills/4ge-cli.md
+ * - dev:   src/core/skill/installer.ts  -> ../../skills/4ge-cli.md
+ */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_SKILL_PATH = resolve(MODULE_DIR, '..', '..', '..', 'skills', '4ge-cli.md');
+/**
+ * Read the canonical bundled skill content.
+ */
+export async function getSkillContent() {
+    return readFile(BUNDLED_SKILL_PATH, 'utf-8');
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install the 4ge CLI skill file to the resolved agent directory.
+ *
+ * Creates the target directory (recursive). Refuses to overwrite an existing
+ * skill file unless `force` is true.
+ */
+export async function installSkill(options) {
+    const resolved = resolveSkillPath({
+        agent: options.agent,
+        scope: options.scope,
+        cwd: options.cwd,
+        home: options.home,
+    });
+    const exists = await fileExists(resolved.path);
+    if (exists && !options.force) {
+        throw new Error(`Skill file already exists at ${resolved.path}. Re-run with --force to overwrite.`);
+    }
+    const content = await getSkillContent();
+    await mkdir(resolved.dir, { recursive: true });
+    await writeFile(resolved.path, content, 'utf-8');
+    return {
+        path: resolved.path,
+        agent: resolved.agent,
+        scope: resolved.scope,
+        overwritten: exists,
+    };
+}
+/**
+ * Re-exported for command-layer convenience.
+ */
+export { resolveSkillPath } from './paths.js';

package/dist/core/skill/paths.js

@@ -0,0 +1,52 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import process from 'node:process';
+/**
+ * Agent skill directory conventions.
+ *
+ * Mirrors the `npx skills` (vercel-labs/skills) convention:
+ * - Project scope: `./<agent>/skills/`
+ * - User scope: `~/<agent>/skills/` (per-agent home dir)
+ *
+ * `universal` is the shared default used by Cursor, Cline, Codex, Gemini CLI,
+ * GitHub Copilot, OpenCode, and others.
+ */
+export const AGENT_SKILL_DIRS = {
+    universal: { project: '.agents/skills', user: '.config/agents/skills' },
+    pi: { project: '.pi/skills', user: '.pi/agent/skills' },
+    'claude-code': { project: '.claude/skills', user: '.claude/skills' },
+    cursor: { project: '.cursor/skills', user: '.cursor/skills' },
+    codex: { project: '.agents/skills', user: '.codex/skills' },
+    'gemini-cli': { project: '.agents/skills', user: '.gemini/skills' },
+    windsurf: { project: '.windsurf/skills', user: '.codeium/windsurf/skills' },
+    continue: { project: '.continue/skills', user: '.continue/skills' },
+};
+export function isKnownAgent(agent) {
+    return Object.prototype.hasOwnProperty.call(AGENT_SKILL_DIRS, agent);
+}
+const SKILL_NAME = '4ge-cli';
+const SKILL_FILE = 'SKILL.md';
+/**
+ * Resolve the absolute path for a skill file, following the `npx skills`
+ * directory convention. Throws on unknown agent names.
+ */
+export function resolveSkillPath(options) {
+    const agent = options.agent ?? 'universal';
+    const scope = options.scope ?? 'project';
+    if (!isKnownAgent(agent)) {
+        throw new Error(`Unknown agent "${agent}". Known agents: ${Object.keys(AGENT_SKILL_DIRS).join(', ')}`);
+    }
+    const dirs = AGENT_SKILL_DIRS[agent];
+    const baseRelative = scope === 'project' ? dirs.project : dirs.user;
+    const base = scope === 'project'
+        ? (options.cwd ?? process.cwd())
+        : (options.home ?? homedir());
+    const dir = join(base, baseRelative, SKILL_NAME);
+    return {
+        dir,
+        file: SKILL_FILE,
+        path: join(dir, SKILL_FILE),
+        agent,
+        scope,
+    };
+}

package/dist/generated/api/client/client.gen.js

@@ -0,0 +1,217 @@
+// This file is auto-generated by @hey-api/openapi-ts
+import { createSseClient } from "../core/serverSentEvents.gen.js";
+import { getValidRequestBody } from "../core/utils.gen.js";
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from "./utils.gen.js";
+export const createClient = (config = {}) => {
+    let _config = mergeConfigs(createConfig(), config);
+    const getConfig = () => ({ ..._config });
+    const setConfig = (config) => {
+        _config = mergeConfigs(_config, config);
+        return getConfig();
+    };
+    const interceptors = createInterceptors();
+    const beforeRequest = async (options) => {
+        const opts = {
+            ..._config,
+            ...options,
+            fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+            headers: mergeHeaders(_config.headers, options.headers),
+            serializedBody: undefined,
+        };
+        if (opts.security) {
+            await setAuthParams(opts);
+        }
+        if (opts.requestValidator) {
+            await opts.requestValidator(opts);
+        }
+        if (opts.body !== undefined && opts.bodySerializer) {
+            opts.serializedBody = opts.bodySerializer(opts.body);
+        }
+        // remove Content-Type header if body is empty to avoid sending invalid requests
+        if (opts.body === undefined || opts.serializedBody === "") {
+            opts.headers.delete("Content-Type");
+        }
+        const resolvedOpts = opts;
+        const url = buildUrl(resolvedOpts);
+        return { opts: resolvedOpts, url };
+    };
+    const request = async (options) => {
+        const throwOnError = options.throwOnError ?? _config.throwOnError;
+        const responseStyle = options.responseStyle ?? _config.responseStyle;
+        let request;
+        let response;
+        try {
+            const { opts, url } = await beforeRequest(options);
+            const requestInit = {
+                redirect: "follow",
+                ...opts,
+                body: getValidRequestBody(opts),
+            };
+            request = new Request(url, requestInit);
+            for (const fn of interceptors.request.fns) {
+                if (fn) {
+                    request = await fn(request, opts);
+                }
+            }
+            // fetch must be assigned here, otherwise it would throw the error:
+            // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+            const _fetch = opts.fetch;
+            response = await _fetch(request);
+            for (const fn of interceptors.response.fns) {
+                if (fn) {
+                    response = await fn(response, request, opts);
+                }
+            }
+            const result = {
+                request,
+                response,
+            };
+            if (response.ok) {
+                const parseAs = (opts.parseAs === "auto"
+                    ? getParseAs(response.headers.get("Content-Type"))
+                    : opts.parseAs) ?? "json";
+                if (response.status === 204 ||
+                    response.headers.get("Content-Length") === "0") {
+                    let emptyData;
+                    switch (parseAs) {
+                        case "arrayBuffer":
+                        case "blob":
+                        case "text":
+                            emptyData = await response[parseAs]();
+                            break;
+                        case "formData":
+                            emptyData = new FormData();
+                            break;
+                        case "stream":
+                            emptyData = response.body;
+                            break;
+                        case "json":
+                        default:
+                            emptyData = {};
+                            break;
+                    }
+                    return opts.responseStyle === "data"
+                        ? emptyData
+                        : {
+                            data: emptyData,
+                            ...result,
+                        };
+                }
+                let data;
+                switch (parseAs) {
+                    case "arrayBuffer":
+                    case "blob":
+                    case "formData":
+                    case "text":
+                        data = await response[parseAs]();
+                        break;
+                    case "json": {
+                        // Some servers return 200 with no Content-Length and empty body.
+                        // response.json() would throw; read as text and parse if non-empty.
+                        const text = await response.text();
+                        data = text ? JSON.parse(text) : {};
+                        break;
+                    }
+                    case "stream":
+                        return opts.responseStyle === "data"
+                            ? response.body
+                            : {
+                                data: response.body,
+                                ...result,
+                            };
+                }
+                if (parseAs === "json") {
+                    if (opts.responseValidator) {
+                        await opts.responseValidator(data);
+                    }
+                    if (opts.responseTransformer) {
+                        data = await opts.responseTransformer(data);
+                    }
+                }
+                return opts.responseStyle === "data"
+                    ? data
+                    : {
+                        data,
+                        ...result,
+                    };
+            }
+            const textError = await response.text();
+            let jsonError;
+            try {
+                jsonError = JSON.parse(textError);
+            }
+            catch {
+                // noop
+            }
+            throw jsonError ?? textError;
+        }
+        catch (error) {
+            let finalError = error;
+            for (const fn of interceptors.error.fns) {
+                if (fn) {
+                    finalError = await fn(finalError, response, request, options);
+                }
+            }
+            finalError = finalError || {};
+            if (throwOnError) {
+                throw finalError;
+            }
+            // TODO: we probably want to return error and improve types
+            return responseStyle === "data"
+                ? undefined
+                : {
+                    error: finalError,
+                    request,
+                    response,
+                };
+        }
+    };
+    const makeMethodFn = (method) => (options) => request({ ...options, method });
+    const makeSseFn = (method) => async (options) => {
+        const { opts, url } = await beforeRequest(options);
+        return createSseClient({
+            ...opts,
+            body: opts.body,
+            method,
+            onRequest: async (url, init) => {
+                let request = new Request(url, init);
+                for (const fn of interceptors.request.fns) {
+                    if (fn) {
+                        request = await fn(request, opts);
+                    }
+                }
+                return request;
+            },
+            serializedBody: getValidRequestBody(opts),
+            url,
+        });
+    };
+    const _buildUrl = (options) => buildUrl({ ..._config, ...options });
+    return {
+        buildUrl: _buildUrl,
+        connect: makeMethodFn("CONNECT"),
+        delete: makeMethodFn("DELETE"),
+        get: makeMethodFn("GET"),
+        getConfig,
+        head: makeMethodFn("HEAD"),
+        interceptors,
+        options: makeMethodFn("OPTIONS"),
+        patch: makeMethodFn("PATCH"),
+        post: makeMethodFn("POST"),
+        put: makeMethodFn("PUT"),
+        request,
+        setConfig,
+        sse: {
+            connect: makeSseFn("CONNECT"),
+            delete: makeSseFn("DELETE"),
+            get: makeSseFn("GET"),
+            head: makeSseFn("HEAD"),
+            options: makeSseFn("OPTIONS"),
+            patch: makeSseFn("PATCH"),
+            post: makeSseFn("POST"),
+            put: makeSseFn("PUT"),
+            trace: makeSseFn("TRACE"),
+        },
+        trace: makeMethodFn("TRACE"),
+    };
+};

package/dist/generated/api/client/index.js

@@ -0,0 +1,6 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from "../core/bodySerializer.gen.js";
+export { buildClientParams } from "../core/params.gen.js";
+export { serializeQueryKeyValue } from "../core/queryKeySerializer.gen.js";
+export { createClient } from "./client.gen.js";
+export { createConfig, mergeHeaders } from "./utils.gen.js";

package/dist/generated/api/client/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};