@skrr-ai/cli 0.1.8

package/dist/lib/keychain.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setActiveProfile = setActiveProfile;
+exports.getActiveProfile = getActiveProfile;
+exports.__currentServiceForTest = __currentServiceForTest;
+exports.isAvailable = isAvailable;
+exports.resetAvailability = resetAvailability;
+exports.readToken = readToken;
+exports.writeToken = writeToken;
+exports.readRefreshToken = readRefreshToken;
+exports.writeRefreshToken = writeRefreshToken;
+exports.readServerOrigin = readServerOrigin;
+exports.writeServerOrigin = writeServerOrigin;
+exports.deleteServerOrigin = deleteServerOrigin;
+exports.deleteToken = deleteToken;
+exports.deleteRefreshToken = deleteRefreshToken;
+exports.deleteAll = deleteAll;
+/**
+ * keychain.ts — macOS Keychain-backed token storage for the Sky CLI.
+ *
+ * Mirrors `daemon/src/keychain.ts` but simpler:
+ *   - No prefetch: the CLI is a short-lived foreground process; parallelizing
+ *     the keychain probe with other startup work isn't worth the code.
+ *   - Namespaced `ai.skrr.cli.<profile>` from day one. Before Phase K
+ *     ships profile switching, `<profile>` is always `default`, but baking
+ *     the suffix in now makes the future migration a rename instead of a
+ *     schema change.
+ *   - Distinct service from the daemon (`ai.skrr.cli.*` vs.
+ *     `ai.skrr.daemon.*`). The CLI holds `scope: 'cli'` tokens; the
+ *     daemon holds `scope: 'daemon'`. They must never read each other's
+ *     items — `skrr login` would overwrite a running daemon's creds and
+ *     vice-versa.
+ *
+ * Layout in the user's login keychain:
+ *   service = "ai.skrr.cli.<profile>"
+ *   account = "cli-token"             → the JWT itself (or CI bootstrap)
+ *   account = "cli-token-expires"     → epoch ms expiry, optional
+ *   account = "cli-refresh"           → refresh JWT
+ *   account = "cli-refresh-expires"   → epoch ms expiry, optional
+ *   account = "cli-server-origin"     → issuing API origin (non-secret)
+ *
+ * On non-darwin (Linux/CI) every function is a no-op / null-return so the
+ * caller cleanly falls back to the file-based `cli-auth.json` backend.
+ */
+const node_child_process_1 = require("node:child_process");
+const cred_envelope_1 = require("./cred-envelope");
+/** Service-name prefix. Always followed by `.<profile>`. */
+const SERVICE_BASE = 'ai.skrr.cli';
+/** Pre-Phase-K namespace; reserved for a future migration helper. */
+const DEFAULT_PROFILE = 'default';
+const ACCOUNT_TOKEN = 'cli-token';
+const ACCOUNT_EXPIRES = 'cli-token-expires';
+const ACCOUNT_REFRESH = 'cli-refresh';
+const ACCOUNT_REFRESH_EXPIRES = 'cli-refresh-expires';
+const ACCOUNT_SERVER_ORIGIN = 'cli-server-origin';
+/** macOS `security` exit code when the requested item does not exist. */
+const SECURITY_ITEM_NOT_FOUND = 44;
+/** Cached availability — probed once at first call. */
+let _availability = null;
+/**
+ * Active profile for this process. Phase K will wire `setActiveProfile('work')`
+ * onto a `--profile` flag; today everything resolves to `default`.
+ */
+let _activeProfile = DEFAULT_PROFILE;
+function setActiveProfile(profile) {
+    if (profile && profile.length > 0)
+        _activeProfile = profile;
+}
+function getActiveProfile() {
+    return _activeProfile;
+}
+function currentService() {
+    return `${SERVICE_BASE}.${_activeProfile}`;
+}
+/** @internal exposed for tests / diagnostics. */
+function __currentServiceForTest() {
+    return currentService();
+}
+function probeAvailability() {
+    if (process.platform !== 'darwin')
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)('security', ['help'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True iff this process can shell out to `security(1)` — i.e. macOS with
+ * the binary on PATH. Result is cached after the first call so callers can
+ * probe cheaply on every read.
+ */
+function isAvailable() {
+    if (_availability === null) {
+        _availability = probeAvailability();
+    }
+    return _availability;
+}
+/**
+ * Invalidate the cached availability decision. Call after an unexpected
+ * keychain read/write failure so a transient lock/signature issue doesn't
+ * masquerade as "keychain always available" across the process lifetime.
+ */
+function resetAvailability() {
+    _availability = null;
+}
+/**
+ * True for accounts that store JWT secrets and should pass through the
+ * L12 envelope on read/write. Expires-at slots stay plaintext — they're
+ * integers and not security-sensitive on their own.
+ */
+function isSecretAccount(account) {
+    return account === ACCOUNT_TOKEN || account === ACCOUNT_REFRESH;
+}
+function readSlot(account, service = currentService()) {
+    let raw;
+    try {
+        const out = (0, node_child_process_1.execFileSync)('security', ['find-generic-password', '-s', service, '-a', account, '-w'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+        const trimmed = out.replace(/\n$/, '');
+        if (trimmed.length === 0)
+            return null;
+        raw = trimmed;
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === SECURITY_ITEM_NOT_FOUND)
+            return null;
+        // Locked keychain, bad signature, etc. — fall through silently so the
+        // caller can try the file backend. Log at stderr so a curious operator
+        // running with `DEBUG=1` can see it; ordinary CLI UX is unaffected.
+        if (process.env.DEBUG) {
+            console.error(`[cli/keychain] find-generic-password failed for ${account} (status=${status ?? 'unknown'})`);
+        }
+        return null;
+    }
+    if (!isSecretAccount(account))
+        return raw;
+    // L12 — route secret slots through the envelope.
+    // - Envelope on disk + path active → returns plaintext.
+    // - Envelope on disk + path inactive → returns null (treat as forced
+    //   re-login; the bundle is unrecoverable without the DEK).
+    // - Legacy plaintext + path active → returns plaintext + needsMigration;
+    //   we re-write in place to upgrade the slot.
+    const result = (0, cred_envelope_1.maybeDecryptOnRead)(raw);
+    if (result.plaintext === null)
+        return null;
+    if (result.needsMigration) {
+        // Best-effort upgrade — a failure here doesn't break the read; the
+        // slot just stays plaintext and we'll try again on the next read.
+        try {
+            writeSlot(account, result.plaintext, service);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return result.plaintext;
+}
+/**
+ * Escape a value for `security -i` (stdin interactive mode).
+ * `security` accepts double-quoted args with `\"` and `\\` backslash escapes.
+ */
+function quoteForSecurityInteractive(v) {
+    return '"' + v.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+function writeSlot(account, value, service = currentService()) {
+    try {
+        // L12 — wrap secret-bearing slots through the envelope when active.
+        // Empty / non-secret slots are passthrough.
+        const wireValue = isSecretAccount(account) ? (0, cred_envelope_1.maybeEncryptForWrite)(value) : value;
+        // -i reads commands from stdin so the JWT never appears in argv (it
+        // would otherwise be visible to same-UID `ps` observers). -U updates
+        // in place instead of failing with "item already exists".
+        const cmd = `add-generic-password -s ${quoteForSecurityInteractive(service)} ` +
+            `-a ${quoteForSecurityInteractive(account)} ` +
+            `-w ${quoteForSecurityInteractive(wireValue)} -U\n`;
+        (0, node_child_process_1.execFileSync)('security', ['-i'], {
+            stdio: ['pipe', 'ignore', 'ignore'],
+            input: cmd,
+        });
+        return true;
+    }
+    catch (err) {
+        const status = err.status;
+        if (process.env.DEBUG) {
+            console.error(`[cli/keychain] add-generic-password failed for ${account} (status=${status ?? 'unknown'})`);
+        }
+        return false;
+    }
+}
+function deleteSlot(account, service = currentService()) {
+    try {
+        (0, node_child_process_1.execFileSync)('security', ['delete-generic-password', '-s', service, '-a', account], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === SECURITY_ITEM_NOT_FOUND)
+            return; // already gone
+        if (process.env.DEBUG) {
+            console.error(`[cli/keychain] delete-generic-password failed for ${account} (status=${status ?? 'unknown'})`);
+        }
+    }
+}
+function readToken() {
+    if (!isAvailable())
+        return null;
+    const token = readSlot(ACCOUNT_TOKEN);
+    if (!token)
+        return null;
+    const expiresRaw = readSlot(ACCOUNT_EXPIRES);
+    let expiresAt;
+    if (expiresRaw) {
+        const parsed = Number.parseInt(expiresRaw, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            expiresAt = parsed;
+    }
+    return expiresAt !== undefined ? { token, expiresAt } : { token };
+}
+function writeToken(token, expiresAt) {
+    if (!isAvailable())
+        return false;
+    if (!token)
+        return false;
+    if (!writeSlot(ACCOUNT_TOKEN, token))
+        return false;
+    if (expiresAt && Number.isFinite(expiresAt)) {
+        writeSlot(ACCOUNT_EXPIRES, String(Math.trunc(expiresAt)));
+    }
+    else {
+        // Stale expiry from a prior write would lie about the token's lifetime.
+        deleteSlot(ACCOUNT_EXPIRES);
+    }
+    return true;
+}
+function readRefreshToken() {
+    if (!isAvailable())
+        return null;
+    const token = readSlot(ACCOUNT_REFRESH);
+    if (!token)
+        return null;
+    const expiresRaw = readSlot(ACCOUNT_REFRESH_EXPIRES);
+    let expiresAt;
+    if (expiresRaw) {
+        const parsed = Number.parseInt(expiresRaw, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            expiresAt = parsed;
+    }
+    return expiresAt !== undefined ? { token, expiresAt } : { token };
+}
+function writeRefreshToken(token, expiresAt) {
+    if (!isAvailable())
+        return false;
+    if (!token)
+        return false;
+    if (!writeSlot(ACCOUNT_REFRESH, token))
+        return false;
+    if (expiresAt && Number.isFinite(expiresAt)) {
+        writeSlot(ACCOUNT_REFRESH_EXPIRES, String(Math.trunc(expiresAt)));
+    }
+    else {
+        deleteSlot(ACCOUNT_REFRESH_EXPIRES);
+    }
+    return true;
+}
+/**
+ * Read the API origin that issued the active token bundle.
+ *
+ * This companion slot is deliberately non-secret. It prevents a token
+ * minted by one skrr environment (for example oversky.dev) from being
+ * replayed against another after Desktop updates cli-config.json#baseURL.
+ * Legacy bundles have no slot and therefore return null; origin-aware
+ * callers fail closed and recover through daemon-broker or `skrr login`.
+ */
+function readServerOrigin() {
+    if (!isAvailable())
+        return null;
+    const value = readSlot(ACCOUNT_SERVER_ORIGIN);
+    return value && value.length > 0 ? value : null;
+}
+/** Persist the issuing API origin alongside the token pair. */
+function writeServerOrigin(origin) {
+    if (!isAvailable())
+        return false;
+    if (!origin)
+        return false;
+    return writeSlot(ACCOUNT_SERVER_ORIGIN, origin);
+}
+/** Remove the issuing-origin companion slot. */
+function deleteServerOrigin() {
+    if (!isAvailable())
+        return;
+    deleteSlot(ACCOUNT_SERVER_ORIGIN);
+}
+function deleteToken() {
+    if (!isAvailable())
+        return;
+    deleteSlot(ACCOUNT_TOKEN);
+    deleteSlot(ACCOUNT_EXPIRES);
+}
+function deleteRefreshToken() {
+    if (!isAvailable())
+        return;
+    deleteSlot(ACCOUNT_REFRESH);
+    deleteSlot(ACCOUNT_REFRESH_EXPIRES);
+}
+/**
+ * Remove every CLI keychain slot for the active profile. Used by `skrr logout`.
+ * Safe to call on a clean system — missing items are not an error.
+ */
+function deleteAll() {
+    deleteToken();
+    deleteRefreshToken();
+    deleteServerOrigin();
+}

package/dist/lib/label-scope.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared plumbing for the unified label commands (`skrr labels …`).
+ *
+ * Labels are anchored to exactly one scope — a user, a space, or a workspace —
+ * via the `(scope, scopeId)` pair. That pair is simultaneously the uniqueness
+ * key and the permission boundary server-side (see
+ * `api/server/services/Labels/LabelService.js`), so every label command has to
+ * name it. There is no ambient workspace context in the CLI, so the scope is
+ * always explicit; `user` is the default because that is the only scope whose
+ * id the server can infer (it falls back to the caller).
+ */
+export declare const LABEL_SCOPES: readonly ["user", "space", "workspace"];
+export type LabelScope = (typeof LABEL_SCOPES)[number];
+export declare const LABEL_APPLICABLE: readonly ["task", "space", "goal", "routine"];
+export type LabelApplicable = (typeof LABEL_APPLICABLE)[number];
+/**
+ * The server stores colors as bare 6-hex (`api/server/routes/labels.js` Zod is
+ * `/^[0-9a-fA-F]{6}$/`, NO leading `#`). We accept both forms and strip.
+ */
+export declare const HEX_COLOR_RE: RegExp;
+export declare function normalizeLabelColor(input: string): string;
+/** `--scope` / `--scope-id`, shared by every `skrr labels` command. */
+export declare const labelScopeFlags: {
+    scope: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    'scope-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+};
+export interface ResolvedLabelScope {
+    scope: LabelScope;
+    scopeId?: string;
+}
+/**
+ * Validate the scope pair. Throws a plain `Error` so callers can surface it
+ * through `this.error(..., { exit: 1 })` with the rest of their flag checks.
+ */
+export declare function resolveLabelScope(flags: {
+    scope?: string;
+    'scope-id'?: string;
+}): ResolvedLabelScope;
+/** Validate a repeatable `--applicable-to` flag against the server enum. */
+export declare function resolveApplicableTo(values?: string[]): LabelApplicable[] | undefined;

package/dist/lib/label-scope.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Shared plumbing for the unified label commands (`skrr labels …`).
+ *
+ * Labels are anchored to exactly one scope — a user, a space, or a workspace —
+ * via the `(scope, scopeId)` pair. That pair is simultaneously the uniqueness
+ * key and the permission boundary server-side (see
+ * `api/server/services/Labels/LabelService.js`), so every label command has to
+ * name it. There is no ambient workspace context in the CLI, so the scope is
+ * always explicit; `user` is the default because that is the only scope whose
+ * id the server can infer (it falls back to the caller).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.labelScopeFlags = exports.HEX_COLOR_RE = exports.LABEL_APPLICABLE = exports.LABEL_SCOPES = void 0;
+exports.normalizeLabelColor = normalizeLabelColor;
+exports.resolveLabelScope = resolveLabelScope;
+exports.resolveApplicableTo = resolveApplicableTo;
+const core_1 = require("@oclif/core");
+exports.LABEL_SCOPES = ['user', 'space', 'workspace'];
+exports.LABEL_APPLICABLE = ['task', 'space', 'goal', 'routine'];
+/**
+ * The server stores colors as bare 6-hex (`api/server/routes/labels.js` Zod is
+ * `/^[0-9a-fA-F]{6}$/`, NO leading `#`). We accept both forms and strip.
+ */
+exports.HEX_COLOR_RE = /^#?[0-9a-fA-F]{6}$/;
+function normalizeLabelColor(input) {
+    return input.replace(/^#/, '');
+}
+/** `--scope` / `--scope-id`, shared by every `skrr labels` command. */
+exports.labelScopeFlags = {
+    scope: core_1.Flags.string({
+        description: 'Label scope',
+        options: [...exports.LABEL_SCOPES],
+        default: 'user',
+    }),
+    'scope-id': core_1.Flags.string({
+        description: 'Space or workspace ID — required for --scope space|workspace. Omit for --scope user (defaults to you).',
+    }),
+};
+/**
+ * Validate the scope pair. Throws a plain `Error` so callers can surface it
+ * through `this.error(..., { exit: 1 })` with the rest of their flag checks.
+ */
+function resolveLabelScope(flags) {
+    const scope = (flags.scope ?? 'user');
+    const scopeId = flags['scope-id'];
+    if ((scope === 'space' || scope === 'workspace') && !scopeId) {
+        throw new Error(`--scope-id is required for --scope ${scope}.`);
+    }
+    if (scope === 'user' && scopeId) {
+        throw new Error('--scope-id is not accepted for --scope user; user-scope labels are always your own.');
+    }
+    return { scope, ...(scopeId ? { scopeId } : {}) };
+}
+/** Validate a repeatable `--applicable-to` flag against the server enum. */
+function resolveApplicableTo(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const invalid = values.filter((v) => !exports.LABEL_APPLICABLE.includes(v));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid --applicable-to value(s): ${invalid.join(', ')}. Allowed: ${exports.LABEL_APPLICABLE.join(', ')}.`);
+    }
+    return values;
+}

package/dist/lib/login.d.ts

@@ -0,0 +1,78 @@
+export interface CliLoginOptions {
+    /** Server base URL. Defaults to config. */
+    serverUrl?: string;
+    /** Token scope. CLI default is 'cli'; 'daemon' reserved for future
+     *  one-shot daemon-token mints from sky (not yet used). */
+    scope?: 'cli' | 'daemon';
+    /** Force device-code (wired to `--device-code`). */
+    forceDeviceCode?: boolean;
+    /** Explicit local-callback port. 0 / undefined = ephemeral. */
+    port?: number;
+    /** User-facing device label shown on the consent page. */
+    deviceName?: string;
+}
+export interface CliLoginResult {
+    token: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    refreshExpiresAt?: number;
+    /** The flow that produced the token; for diagnostics / telemetry. */
+    flow: 'localhost' | 'device-code' | 'refresh-token' | 'daemon-broker';
+}
+export interface CliLoginWithRefreshTokenOptions {
+    /** Server base URL. Defaults to config. */
+    serverUrl?: string;
+    /** Long-lived refresh token from a prior `skrr login`, restored from a backup. */
+    refreshToken: string;
+    /**
+     * The cliId the refresh token was issued for. The server's
+     * `/api/daemons/token/refresh` route binds rows to a daemonId/cliId so
+     * the family-reuse detector can flag a token replayed under a different
+     * device identity — that binding is what makes us reject this call when
+     * the cliId doesn't match.
+     *
+     * Operators backing up auth to 1Password should record BOTH this and
+     * the refresh token. CC's analog (CC-A-7 / CLAUDE_CODE_OAUTH_REFRESH_TOKEN)
+     * accepts the refresh alone because their device-binding is softer; we
+     * keep ours strict on purpose.
+     */
+    cliId: string;
+}
+/**
+ * Top-level dispatcher. Picks PKCE localhost vs device-code per the
+ * decision tree in the roadmap and persists the result.
+ */
+export declare function cliLogin(opts?: CliLoginOptions): Promise<CliLoginResult>;
+/**
+ * L13 (CC-A-7) — non-interactive login from a refresh token.
+ *
+ * When `skrr login` runs with `OVERSKY_REFRESH_TOKEN` in the environment,
+ * skip every interactive flow and exchange the refresh token for a fresh
+ * (access, refresh) pair via `POST /api/daemons/token/refresh`. The
+ * rotated pair is persisted via the same `writeToBackend()` path PKCE
+ * and device-code use, so a follow-up `sky <command>` finds it in the
+ * normal place (Keychain on macOS, `cli-auth.json` elsewhere).
+ *
+ * Use case: "I rebuilt my server and need to restore CLI auth from
+ * 1Password / a backup, with no human at a browser." Containers, cron
+ * provisioning, Ansible playbooks, EC2 init scripts.
+ *
+ * Why a paired backup (refresh + cliId), not refresh alone:
+ *   skrr's refresh route rejects a token presented under a daemonId
+ *   that doesn't match the row's binding — that mismatch is what makes
+ *   the family-reuse detector useful (a stolen refresh token replayed
+ *   under a different cliId looks different, and the detector can react).
+ *   CC's analog (CLAUDE_CODE_OAUTH_REFRESH_TOKEN) accepts the refresh
+ *   alone because their device-binding is softer; we keep ours strict
+ *   and ask the operator to back up the pair. See
+ *   docs/daemon-auth-cc-deep-comparison-2026-04-24.md L13 for the full
+ *   reasoning.
+ *
+ * Caller is responsible for surfacing the resulting token's source name
+ * to operators — `formatCredentialSource` renders 'env-token' for the
+ * raw OVERSKY_TOKEN slot, but this function persists into the storage
+ * backend, so a subsequent `skrr whoami` will report 'macOS Keychain' /
+ * 'auth.json' rather than 'OVERSKY_REFRESH_TOKEN'. That's the right
+ * outcome — the refresh token has been consumed and replaced.
+ */
+export declare function cliLoginWithRefreshToken(opts: CliLoginWithRefreshTokenOptions): Promise<CliLoginResult>;