@4ge/cli 0.2.1 → 0.2.3

package/dist/base.js

@@ -177,21 +177,47 @@ export class BaseCommand extends Command {
             },
         }, null, 2));
     }
+    /**
+     * Render an error respecting the active output mode.
+     *
+     * - JSON mode: emit the structured `{ data, error, metadata }` envelope.
+     * - Pretty mode: render a human-readable error (never a JSON blob) using
+     *   oclif's `error()`, which pretty-prints to stderr and exits non-zero.
+     *
+     * Centralising the mode branch here means command authors can call
+     * `outputErrorAndExit({ message, code, hint })` without guarding on
+     * `isJsonMode` themselves — eliminating a class of bug where pretty-mode
+     * users saw raw JSON error envelopes.
+     */
     outputError(error, metadata) {
         const errorObj = typeof error === 'string'
             ? { message: error }
             : error;
-        this.log(JSON.stringify({
-            data: null,
-            error: errorObj,
-            metadata: {
-                timestamp: new Date().toISOString(),
-                ...metadata,
-            },
-        }, null, 2));
+        if (this.isJsonMode) {
+            this.log(JSON.stringify({
+                data: null,
+                error: errorObj,
+                metadata: {
+                    timestamp: new Date().toISOString(),
+                    ...metadata,
+                },
+            }, null, 2));
+            return;
+        }
+        // Pretty mode — mirror the human format used by handleError():
+        //   <message>
+        //   💡 <hint>
+        // oclif's error() throws a PrettyPrintableError caught by the framework;
+        // it never returns, so callers chained off outputError() (e.g.
+        // outputErrorAndExit) reliably terminate.
+        const lines = [errorObj.message];
+        if (errorObj.hint)
+            lines.push(`💡 ${errorObj.hint}`);
+        this.error(lines.join('\n'));
     }
     outputErrorAndExit(error, metadata) {
         this.outputError(error, metadata);
+        // Only reached in JSON mode — in pretty mode outputError() throws.
         this.exit(1);
     }
     /**

package/dist/commands/auth/status.js

@@ -3,6 +3,8 @@ import { resolveCredential } from '../../core/auth/resolution.js';
 import { createApiClient, ConnectivityError } from '../../core/auth/api-client.js';
 import { ensureFreshToken } from '../../core/auth/token-refresh.js';
 import { cliAuthStatus } from '../../generated/api/sdk.gen.js';
+import { zCliAuthStatusResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
 export default class AuthStatus extends BaseCommand {
     static description = 'Check authentication status';
     async run() {
@@ -85,8 +87,15 @@ export default class AuthStatus extends BaseCommand {
                 }
                 return;
             }
+            // Validate the envelope against the generated schema and extract the
+            // typed user. Uses the same boundary-validation seam as every other
+            // command (the generated zCliAuthStatusResponse now types data.user,
+            // data.workspaces, and the authenticated_as enum in lockstep with the
+            // app's CLIAuthStatusSchema — see docs/cli-api-contract.pin.md).
+            const validated = validateResponse(data, null, zCliAuthStatusResponse);
+            const user = validated.data?.user;
             if (this.isJsonMode) {
-                this.outputJson({ source: activeCredential.source, profile: activeCredential.profile, user: data });
+                this.outputJson({ source: activeCredential.source, profile: activeCredential.profile, user });
             }
             else {
                 if (activeCredential.source === 'environment') {
@@ -96,8 +105,9 @@ export default class AuthStatus extends BaseCommand {
                 this.log(`Source:  ${activeCredential.source}`);
                 if (activeCredential.profile)
                     this.log(`Profile: ${activeCredential.profile}`);
-                if (data)
-                    this.log(`User:    ${data.email || data.id || 'Unknown'}`);
+                // Display precedence per contract §5.8: full_name → username → email → id.
+                if (user)
+                    this.log(`User:    ${user.full_name || user.username || user.email || user.id || 'Unknown'}`);
             }
         }
         catch (error) {

package/dist/core/auth/realtime.js

@@ -66,17 +66,18 @@ export async function subscribeForTokens(opts) {
     };
 }
 /**
- * Get the Supabase URL and anon key from environment variables.
- * Throws if either is missing.
+ * Get the Supabase URL and anon key.
+ *
+ * The anon key is public by design (RLS enforces all security), so the
+ * production values are baked in as defaults — a globally-installed CLI has
+ * no `.env.local` and must still support the OAuth browser flow with zero
+ * user configuration. `SUPABASE_URL` / `SUPABASE_ANON_KEY` env vars override
+ * the defaults (used by `4ge/app` for local dev against a local Supabase).
  */
 export function getSupabaseConfig() {
-    const supabaseUrl = process.env.SUPABASE_URL;
-    const supabaseAnonKey = process.env.SUPABASE_ANON_KEY;
-    if (!supabaseUrl) {
-        throw new Error('SUPABASE_URL environment variable is required for OAuth login. Set it in your .env file or environment.');
-    }
-    if (!supabaseAnonKey) {
-        throw new Error('SUPABASE_ANON_KEY environment variable is required for OAuth login. Set it in your .env file or environment.');
-    }
+    // Production Supabase project backing app.4ge.dev.
+    const supabaseUrl = process.env.SUPABASE_URL || 'https://ujhqusbkvaaczncgzsyo.supabase.co';
+    const supabaseAnonKey = process.env.SUPABASE_ANON_KEY ||
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InVqaHF1c2JrdmFhY3puY2d6c3lvIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTU4NTQ1OTAsImV4cCI6MjA3MTQzMDU5MH0.A0c0oG-Dj0EvEuH8eNOa8y0o81uCNPkjlOFqoUMx170';
     return { supabaseUrl, supabaseAnonKey };
 }

package/dist/core/version-check.js

@@ -0,0 +1,134 @@
+/**
+ * Best-effort npm registry update check for the 4ge CLI.
+ *
+ * Design constraints:
+ * - Never throws. A failed/timeout/missing registry response is a no-op.
+ * - Never blocks the user: hits the registry at most once per `cacheTtlMs`
+ *   (default 24h), persisting the result in a cache file alongside the
+ *   credentials directory.
+ * - Silent in machine/JSON contexts — the caller (the postrun hook) is
+ *   responsible for suppressing output in `--json` mode.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const DEFAULT_REGISTRY_TIMEOUT_MS = 3_000;
+export const NPM_REGISTRY_URL = 'https://registry.npmjs.org';
+export const PACKAGE_NAME = '@4ge/cli';
+/**
+ * Default cache path: `~/.4ge/.update-check.json` (sibling of credentials.json).
+ */
+export function getDefaultCachePath() {
+    return join(homedir(), '.4ge', '.update-check.json');
+}
+/**
+ * Compare two semver strings by their numeric major.minor.patch components.
+ * Prerelease suffixes are ignored (treated as equal to the release).
+ *
+ * @returns -1 if `a < b`, 0 if equal, 1 if `a > b`. Non-parseable parts are
+ *          treated as 0.
+ */
+export function compareVersions(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i];
+        const y = pb[i];
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+}
+function parseSemver(v) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v ?? '');
+    return [
+        m ? Number(m[1]) : 0,
+        m ? Number(m[2]) : 0,
+        m ? Number(m[3]) : 0,
+    ];
+}
+/**
+ * Check the npm registry for a newer published version of the package.
+ *
+ * @returns an {@link UpdateInfo} when an update is available, otherwise `null`.
+ *          Always resolves (never rejects) — safe to call fire-and-forget.
+ */
+export async function checkForUpdate(opts) {
+    const { currentVersion, packageName = PACKAGE_NAME, cachePath = getDefaultCachePath(), cacheTtlMs = DEFAULT_CACHE_TTL_MS, timeoutMs = DEFAULT_REGISTRY_TIMEOUT_MS, registryUrl = NPM_REGISTRY_URL, fetchImpl = globalThis.fetch, } = opts;
+    if (!currentVersion)
+        return null;
+    // 1. Try the cache first.
+    let cached = null;
+    try {
+        const raw = await readFile(cachePath, 'utf-8');
+        cached = JSON.parse(raw);
+    }
+    catch {
+        // Missing or corrupt cache is fine — fall through to a live fetch.
+        cached = null;
+    }
+    const now = Date.now();
+    // "Fresh" means we checked recently, regardless of whether we learned a
+    // version. This gives us negative caching: a failed/offline check is retried
+    // at most once per TTL window instead of adding a network timeout to every
+    // subsequent command.
+    const cacheFresh = cached && typeof cached.lastCheck === 'number' &&
+        (now - cached.lastCheck) < cacheTtlMs;
+    let latest;
+    if (cacheFresh) {
+        // Either reuse a cached version, or (if the last check found nothing)
+        // honour the negative cache and skip a redundant fetch.
+        latest = cached.latest;
+    }
+    else {
+        latest = await fetchLatestVersion(packageName, registryUrl, timeoutMs, fetchImpl);
+        // Persist for next time — including a negative cache entry when fetch
+        // returned nothing, so we don't hammer the registry while offline.
+        await safeWriteCache(cachePath, { lastCheck: now, latest });
+        if (!latest)
+            return null;
+    }
+    if (!latest)
+        return null;
+    const updateAvailable = compareVersions(currentVersion, latest) < 0;
+    if (!updateAvailable)
+        return null;
+    return { current: currentVersion, latest, updateAvailable };
+}
+async function fetchLatestVersion(packageName, registryUrl, timeoutMs, fetchImpl) {
+    if (typeof fetchImpl !== 'function')
+        return undefined;
+    const encoded = encodeURIComponent(packageName);
+    const url = `${registryUrl}/${encoded}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            signal: controller.signal,
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return body?.['dist-tags']?.latest;
+    }
+    catch {
+        // Network error, timeout, malformed JSON — all treated as "no info".
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function safeWriteCache(cachePath, data) {
+    try {
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, JSON.stringify(data), 'utf-8');
+    }
+    catch {
+        // Cache write is best-effort; never propagate.
+    }
+}

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

@@ -57,7 +57,20 @@ export const zCliAuthCallbackResponse = z.object({
  * Successful response
  */
 export const zCliAuthStatusResponse = z.object({
-    data: z.unknown(),
+    data: z.object({
+        user: z.object({
+            id: z.uuid(),
+            email: z.email().nullable(),
+            full_name: z.string().nullish(),
+            username: z.string().nullish(),
+        }),
+        workspaces: z.array(z.object({
+            id: z.uuid(),
+            name: z.string(),
+            role: z.enum(["OWNER", "MEMBER"]),
+        })),
+        authenticated_as: z.enum(["session", "api_key"]),
+    }),
     error: z.unknown(),
     metadata: z.object({
         timestamp: z.string(),

package/dist/hooks/postrun.js

@@ -0,0 +1,25 @@
+import { checkForUpdate } from '../core/version-check.js';
+const hook = async (options) => {
+    const { argv, config } = options;
+    // Silence in JSON / machine mode so stdout stays clean.
+    if (argv.includes('--json') || argv.includes('-j'))
+        return;
+    // Unlikely for a published CLI, but don't attempt without a version.
+    const currentVersion = config.version;
+    if (!currentVersion)
+        return;
+    try {
+        const info = await checkForUpdate({ currentVersion });
+        if (info?.updateAvailable) {
+            // Write directly to stderr — oclif's context.warn() also emits a stack
+            // trace via the logger, which is noisy for an advisory notice.
+            const chalk = (await import('chalk')).default;
+            process.stderr.write(chalk.yellow(`\nUpdate available: ${info.current} → ${info.latest}\n` +
+                `  Run \`npm i -g @4ge/cli\` to update.\n`));
+        }
+    }
+    catch {
+        // Never let an update check interfere with the user's command.
+    }
+};
+export default hook;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4ge/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "4ge Service Architecture Bridge & CLI",
   "main": "dist/index.js",
   "bin": {
@@ -26,6 +26,9 @@
     "plugins": [
       "@oclif/plugin-help"
     ],
+    "hooks": {
+      "postrun": "./dist/hooks/postrun.js"
+    },
     "flexibleTaxonomy": true
   },
   "type": "module",

package/skills/4ge-cli.md

@@ -1,3 +1,19 @@
+---
+name: 4ge-cli
+description: >
+  Instructions for AI agents to interact with the 4ge Product Management
+  Platform via the `4ge` CLI. Covers command syntax (namespace:command with a
+  colon), mandatory `--json` agent mode, the response envelope, error handling,
+  discovery, dry-run previews, retry, and the full command reference for the
+  project / epic / story / feature / flow / idea / template / plan / auth /
+  config / skill namespaces. Use when an agent needs to read or mutate 4ge plan
+  assets, work with pull/list/show/update commands, or install the 4ge CLI skill
+  for an agent harness.
+user-invocable: true
+risk: safe
+source: https://github.com/Conflate-AI/4ge-cli/blob/main/skills/4ge-cli.md
+---
+
 # 4ge CLI Skill
 
 This document provides instructions for AI agents to interact with the 4ge