@soku-ai/cli 0.1.0-alpha.0

package/dist/update-check.js

@@ -0,0 +1,204 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { configDir } from './config.js';
+import { cyan, dim, emitError, emitSuccess, ExitCode } from './output/envelope.js';
+import { CLI_PACKAGE_NAME, CLI_VERSION } from './version.js';
+const DEFAULT_REGISTRY_URL = 'https://registry.npmjs.org';
+const INSTALL_COMMAND = `npm i -g ${CLI_PACKAGE_NAME}`;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 2500;
+function cachePath() {
+    return join(configDir(), 'update-check.json');
+}
+function readCache(now) {
+    try {
+        const cache = JSON.parse(readFileSync(cachePath(), 'utf8'));
+        const checkedAt = new Date(cache.checked_at).getTime();
+        if (!Number.isFinite(checkedAt))
+            return null;
+        if (now.getTime() - checkedAt > CACHE_TTL_MS)
+            return null;
+        return cache;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cache) {
+    const path = cachePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+}
+function parseVersionParts(version) {
+    const core = version.split('-', 1)[0] ?? '';
+    return core.split('.').map((part) => {
+        const n = Number(part);
+        return Number.isFinite(n) ? n : 0;
+    });
+}
+function prereleaseParts(version) {
+    const idx = version.indexOf('-');
+    if (idx === -1)
+        return [];
+    return version.slice(idx + 1).split(/[.+]/).filter(Boolean);
+}
+function comparePrerelease(a, b) {
+    const aa = prereleaseParts(a);
+    const bb = prereleaseParts(b);
+    if (aa.length === 0 && bb.length === 0)
+        return 0;
+    if (aa.length === 0)
+        return 1;
+    if (bb.length === 0)
+        return -1;
+    for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+        const left = aa[i];
+        const right = bb[i];
+        if (left === undefined)
+            return -1;
+        if (right === undefined)
+            return 1;
+        const leftNum = /^\d+$/.test(left) ? Number(left) : null;
+        const rightNum = /^\d+$/.test(right) ? Number(right) : null;
+        if (leftNum !== null && rightNum !== null) {
+            const diff = leftNum - rightNum;
+            if (diff !== 0)
+                return diff;
+            continue;
+        }
+        if (leftNum !== null)
+            return -1;
+        if (rightNum !== null)
+            return 1;
+        const diff = left.localeCompare(right);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+export function compareSemverish(a, b) {
+    const aa = parseVersionParts(a);
+    const bb = parseVersionParts(b);
+    for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+        const diff = (aa[i] ?? 0) - (bb[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return comparePrerelease(a, b);
+}
+async function fetchLatestVersion(registryUrl, fetchImpl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await fetchImpl(`${registryUrl.replace(/\/$/, '')}/@soku%2fcli/latest`, {
+            signal: controller.signal,
+            headers: { Accept: 'application/json' },
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            throw new Error(`npm registry returned HTTP ${res.status}`);
+        }
+        const data = (await res.json());
+        if (typeof data.version !== 'string' || data.version.length === 0) {
+            throw new Error('npm registry response did not include a version');
+        }
+        return data.version;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function checkForUpdate(opts = {}) {
+    const currentVersion = opts.currentVersion ?? CLI_VERSION;
+    const registryUrl = (opts.registryUrl ?? DEFAULT_REGISTRY_URL).replace(/\/$/, '');
+    const now = opts.now ?? new Date();
+    if (opts.useCache !== false) {
+        const cache = readCache(now);
+        if (cache) {
+            const latestVersion = cache.latest_version;
+            return {
+                packageName: CLI_PACKAGE_NAME,
+                currentVersion,
+                latestVersion,
+                published: !cache.package_unpublished,
+                updateAvailable: latestVersion !== null && compareSemverish(latestVersion, currentVersion) > 0,
+                installCommand: INSTALL_COMMAND,
+                checkedAt: cache.checked_at,
+                registryUrl,
+            };
+        }
+    }
+    const latestVersion = await fetchLatestVersion(registryUrl, opts.fetchImpl ?? fetch);
+    const checkedAt = now.toISOString();
+    writeCache({
+        checked_at: checkedAt,
+        latest_version: latestVersion,
+        ...(latestVersion === null ? { package_unpublished: true } : {}),
+    });
+    return {
+        packageName: CLI_PACKAGE_NAME,
+        currentVersion,
+        latestVersion,
+        published: latestVersion !== null,
+        updateAvailable: latestVersion !== null && compareSemverish(latestVersion, currentVersion) > 0,
+        installCommand: INSTALL_COMMAND,
+        checkedAt,
+        registryUrl,
+    };
+}
+function shouldSkipNotice() {
+    if (!process.stderr.isTTY)
+        return true;
+    if (process.env.CI)
+        return true;
+    if (process.env.SOKU_NO_UPDATE_CHECK === '1')
+        return true;
+    return false;
+}
+export async function maybeNotifyUpdate() {
+    if (shouldSkipNotice())
+        return;
+    try {
+        const result = await checkForUpdate();
+        if (!result.updateAvailable || !result.latestVersion)
+            return;
+        process.stderr.write(`${dim('Update available:')} ${CLI_PACKAGE_NAME} ${result.currentVersion} -> ${result.latestVersion}\n` +
+            `${dim('Run')} ${cyan(result.installCommand)}\n`);
+    }
+    catch {
+        // Update checks are advisory. Never fail the user command because npm is
+        // unreachable, private, or temporarily returning a malformed response.
+    }
+}
+export function registerUpdateCheckCommand(program) {
+    program
+        .command('update-check')
+        .description('Check whether a newer Soku CLI is available on npm')
+        .option('--registry-url <url>', 'Override the npm registry URL')
+        .action(async (opts) => {
+        try {
+            const result = await checkForUpdate({
+                registryUrl: opts.registryUrl,
+                useCache: false,
+            });
+            emitSuccess(result, (d) => {
+                if (!d.published) {
+                    return `${CLI_PACKAGE_NAME} is not published on npm yet.\n${dim('Use a local linked build for development.')}`;
+                }
+                if (!d.latestVersion)
+                    return `${CLI_PACKAGE_NAME}: no published version found.`;
+                if (!d.updateAvailable)
+                    return `${CLI_PACKAGE_NAME} is up to date (${d.currentVersion}).`;
+                return [
+                    `${CLI_PACKAGE_NAME} ${d.currentVersion} -> ${d.latestVersion}`,
+                    `${dim('Run')} ${cyan(d.installCommand)}`,
+                ].join('\n');
+            });
+        }
+        catch (err) {
+            emitError('update_check_failed', err instanceof Error ? err.message : String(err), ExitCode.RUNTIME, 'Set SOKU_NO_UPDATE_CHECK=1 to disable background checks.');
+        }
+    });
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const CLI_PACKAGE_NAME = "@soku-ai/cli";
+export declare const CLI_VERSION = "0.1.0-alpha.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAC9C,eAAO,MAAM,WAAW,kBAAkB,CAAA"}

package/dist/version.js

@@ -0,0 +1,3 @@
+export const CLI_PACKAGE_NAME = '@soku-ai/cli';
+export const CLI_VERSION = '0.1.0-alpha.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAA;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAA"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@soku-ai/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "Soku CLI — call Soku ads/GA4 data capabilities from any AI agent or shell.",
+  "license": "Proprietary",
+  "author": "Soku",
+  "homepage": "https://soku.ai/cli",
+  "bugs": {
+    "url": "https://github.com/About-Intelligence/nex-studio/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/About-Intelligence/nex-studio.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "soku",
+    "cli",
+    "ai-agent",
+    "marketing-analytics",
+    "google-ads",
+    "ga4"
+  ],
+  "type": "module",
+  "bin": {
+    "soku": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc && mkdir -p dist/generated && cp src/generated/capabilities.json dist/generated/capabilities.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test \".test-build/**/*.test.js\"",
+    "gen:capabilities": "pnpm run build && node scripts/gen-capabilities.ts",
+    "clean": "rm -rf dist .test-build",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "fflate": "^0.8.2",
+    "open": "^10.1.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/soku/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: soku
+description: >-
+  Use when calling Soku ads/GA4 marketing-data capabilities from the shell —
+  running `soku auth login`, switching org/brand with `soku org use` /
+  `soku brand use`, discovering capabilities, calling a data action, routing a
+  third-party API call (Ahrefs/DataForSEO/Firecrawl/Gemini/…) through
+  `soku egress`, handling 401/403 errors, or installing/updating the Soku CLI.
+license: Proprietary
+metadata:
+  author: nex-ad
+  version: "0.1"
+---
+
+# Soku CLI
+
+The `soku` CLI calls Soku's ads + GA4 data capabilities over HTTP. It is the
+preferred way for an agent to use Soku data — it works in any shell, with no MCP
+host required. Output is JSON on stdout; errors are a JSON envelope on stderr
+with a semantic exit code.
+
+## Output & exit codes
+
+Every command prints JSON. When piped (non-TTY) success is
+`{"ok": true, "data": ...}`; errors are `{"ok": false, "error": {"type", "message", "hint"}}`.
+
+| Exit | Meaning | What to do |
+|------|---------|------------|
+| 0 | Success | Parse `data`. |
+| 1 | Usage / no workspace selected | Fix arguments, or run `soku org use` / `soku brand use`. |
+| 2 | Auth — not signed in or token expired/revoked | Run `soku auth login` (or set `SOKU_TOKEN`). |
+| 4 | Not found (unknown capability) | Re-check via `soku --help` / `soku <ns> --help`. |
+| 5 | Runtime / network | Retry; if behind a proxy set `ALL_PROXY`. |
+
+## Authentication
+
+`soku` authenticates once per machine with a long-lived, **org-agnostic** session
+token. The org and brand are chosen at runtime (see Workspace), not at login.
+
+### Agent path (recommended): non-blocking split-flow
+
+Do NOT block a turn waiting for a human at a browser. Start login with
+`--no-wait`, surface the URL, end your turn, then resume:
+
+```bash
+soku auth login --no-wait
+```
+
+This returns immediately, e.g.:
+
+```json
+{"ok":true,"data":{"user_code":"MWVP-ZTSZ","verification_uri":"https://studio.nex.ad/device","verification_uri_complete":"https://studio.nex.ad/device?user_code=MWVP-ZTSZ","device_code":"...","next":"soku auth login --device-code ..."}}
+```
+
+Surface `verification_uri` and `user_code` to the user as your turn's final
+message (treat the URL as an opaque string — do not edit, re-encode, or
+re-assemble it). After the user says they approved, resume polling:
+
+```bash
+soku auth login --device-code <device_code>
+```
+
+### Human path
+
+`soku auth login` opens the browser and polls until the user approves. Add
+`--qr` to render the verification URL as a QR code.
+
+### CI / non-interactive
+
+Set `SOKU_TOKEN` to a pre-issued token; it overrides stored credentials and
+skips all interactive auth. This is the right path for CI and headless agents —
+it also avoids the OS keychain, which may be unavailable in containers.
+
+### Session state
+
+- `soku auth status` — show the current identity.
+- `soku auth logout` — delete the stored token.
+- On exit code 2 with `expired` / `key_revoked`, the stored token is dropped
+  automatically; re-run `soku auth login`.
+
+## Workspace (org + brand)
+
+The session token carries no org/brand. Pick a workspace before calling data
+actions; the selection is saved to `~/.soku/config.json` and sent as
+`X-Soku-Org` / `X-Soku-Brand` headers.
+
+```bash
+soku org list             # organizations you belong to
+soku org use <slug|id>    # set active org (id, slug, or name; clears a now-mismatched brand)
+soku brand list           # brands in the active org
+soku brand use <slug|id>  # id, slug, or name
+```
+
+Env overrides for one-off invocations: `SOKU_ORG_ID`, `SOKU_BRAND_ID`.
+
+## Calling capabilities (discover with --help, then run)
+
+Each data capability is a typed sub-command under its namespace. Discover and
+inspect them with `--help` — never guess action names or flags.
+
+```bash
+soku resources list                       # what's granted (e.g. data-infra)
+soku --help                               # namespaces: ads, ga4, …
+soku ads --help                           # actions in the ads namespace
+soku ads query-single-dimension --help    # flags, types, and usage for one action
+
+soku ads list-ad-accounts --platform google
+soku ads query-single-dimension --account-id 123 --dimension campaign \
+  --date-start 2026-05-01 --date-end 2026-05-18
+```
+
+`<command> --help` is authoritative for valid flags, required vs optional, types,
+and usage. Read it before invoking an unfamiliar action. Object/list flags take a
+JSON string, e.g. `--filters '{"campaign_id":["123"]}'`.
+
+### Raw escape hatch
+
+`soku call <namespace> <action>` runs any action by its raw (snake_case) name
+with a JSON payload. Use it only when a typed sub-command isn't available — e.g.
+a newer action than this CLI version ships:
+
+```bash
+soku call ads list_ad_accounts -p platform=google
+soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'
+```
+
+## Write actions (human approval required)
+
+Some actions mutate state (e.g. conversion-group writes) and are **review-gated**.
+They are NOT in the typed command tree — call them with `soku call` and a
+required `--summary` describing the change. The call does NOT execute; it returns
+a pending review that a human approves.
+
+```bash
+soku call ads create_conversion_group --summary "create group: qualified leads" -p name="Qualified leads"
+# → {"ok":true,"data":{"status":"pending_review","pending_review_id":"<id>","summary":"..."}}
+
+soku review list                  # see pending reviews
+soku review show <id>             # full payload + (after approval) result
+soku review approve <id>          # a human approves → the action executes now
+soku review deny <id> --feedback "wrong account"
+```
+
+- The write resource must be granted to the session (request it at login:
+  `soku auth login --resource data-infra,conversion-groups-write`). Without it,
+  `soku call` returns 403.
+- Approval is **single-use**: one review = one execution. Approving an already
+  decided review is a no-op that returns the existing result.
+- Do NOT loop `soku review approve` expecting retries; a failed approval is
+  terminal — create a fresh `soku call` to try again.
+- As an agent: surface the `pending_review_id` + summary to the user and let
+  THEM run `soku review approve`. Do not approve on the user's behalf.
+
+## Third-party APIs (egress)
+
+Skills that call third-party providers (Ahrefs, DataForSEO, Firecrawl, Gemini, …)
+must route the call through `soku egress`. The credential is injected
+server-side, so **no third-party API key lives on this machine**.
+
+Prefix the skill's `curl` with `soku egress --`:
+
+```bash
+soku egress -- curl -H "Authorization: Bearer $AHREFS_API_KEY" "https://api.ahrefs.com/v3/..."
+```
+
+`$AHREFS_API_KEY` is not set here, and that is expected — `soku egress` strips the
+empty auth header, Soku injects the real key, and the upstream response is
+returned verbatim on stdout.
+
+- Do NOT pre-flight check whether an API key env var is set, and do NOT abort a
+  skill because a key looks missing (no `[ -z "$X_API_KEY" ]` guards, no
+  `if not os.environ.get(...)` early-exits). Assume the credential is available;
+  just make the call through `soku egress`.
+- A skill's own `SKILL.md` shows the raw `curl -H "Authorization: Bearer $X"`
+  form for reference. Ignore whether the key is set — prefix the whole command
+  with `soku egress --`.
+- `soku egress providers` lists the covered hosts. For a host NOT listed, the
+  proxy does not inject a credential — follow that skill's own auth instead.
+
+## Installing / updating the skill
+
+```bash
+soku update-check          # check whether the CLI itself needs updating
+soku skill install            # this meta-skill into .claude / .codex / .cursor (project)
+soku skill install --global   # into ~/.claude, ~/.codex, ~/.cursor
+soku skill install --agent claude --global
+```
+
+If `soku update-check` reports an available CLI update, ask the user before
+running:
+
+```bash
+npm i -g @soku-ai/cli
+```
+
+## Installing business skills (account audits, Google Ads, reports, …)
+
+Beyond this meta-skill, Soku publishes a catalog of domain skills (e.g.
+`account-audit`, `google-ads`, `ads-report`) that already know which `soku call`
+actions and `soku egress` providers to use — install one and your agent gains
+that playbook.
+
+```bash
+soku skill list                       # browse the catalog
+soku skill install account-audit      # install one (into soku-account-audit/)
+soku skill install ads-report google-ads
+soku skill install --all              # install everything
+soku skill installed                  # what's installed locally
+soku skill remove account-audit
+```
+
+Each installed skill carries a "Running this skill with the Soku CLI" section
+(its data actions mapped to `soku call`, its third-party APIs to `soku egress`),
+so it runs through this same CLI — no in-sandbox tools, no local API keys.
+
+## Security rules
+
+- Never print the access token (it grants account access). Prefer `SOKU_TOKEN`
+  for CI rather than echoing it.
+- Reads (`data-infra`) run directly. Writes are review-gated: `soku call`
+  creates a pending review and only `soku review approve` (a human action)
+  executes it. Don't approve on the user's behalf, and don't assume a
+  `--yes`-style bypass exists — there isn't one.
+- Pass user-provided values as separate argv elements (the `-p key=value` form),
+  never by string-concatenating them into a shell command.

package/skills/soku/references/capability-flow.md

@@ -0,0 +1,71 @@
+# Capability discovery flow
+
+A worked example of the discover → inspect → run loop the agent should follow.
+Each data capability is a typed sub-command under its namespace; `--help` is the
+discovery and inspection surface.
+
+## 1. Confirm what's granted
+
+```bash
+soku resources list
+```
+
+```json
+{"ok":true,"data":{"resources":[{"id":"data-infra","label":"Data Infra","description":"Read-only Soku synchronized data actions for ads and GA4.","enabled":true}],"count":1}}
+```
+
+## 2. Discover namespaces and actions with --help
+
+```bash
+soku --help          # top level: namespaces (ads, ga4, …) plus auth/org/brand
+soku ads --help      # actions in the ads namespace
+soku ga4 --help      # actions in the ga4 namespace
+```
+
+Common ads actions:
+
+- `soku ads list-ad-accounts` — discover account_id values (run first when you have none)
+- `soku ads list-dimensions` — discover queryable dimensions/metrics/filters
+- `soku ads query-single-dimension`, `soku ads query-multi-dimension` — metric queries
+- `soku ads gaql-search` — raw Google Ads GAQL
+- `soku ga4 list-properties`, `soku ga4 get-property-overview`, `soku ga4 list-top-pages`, …
+
+## 3. Inspect a command's flags before running
+
+```bash
+soku ads query-single-dimension --help
+```
+
+The help is authoritative for flag names, required vs optional, types, and the
+appended usage notes. Never guess flags — read `--help` first. Object/list flags
+take a JSON string (e.g. `--filters '{"campaign_id":["123"]}'`).
+
+## 4. Run
+
+```bash
+soku ads list-ad-accounts --platform google
+soku ads query-single-dimension \
+  --account-id 1234567890 \
+  --dimension campaign \
+  --date-start 2026-05-01 \
+  --date-end 2026-05-07
+```
+
+## Raw escape hatch
+
+When no typed sub-command exists for an action (e.g. a newer action than this
+CLI version ships), call it by its raw snake_case name:
+
+```bash
+soku call ads query_single_dimension --payload '{"account_id":"1234567890","dimension":"campaign","date_start":"2026-05-01","date_end":"2026-05-07"}'
+```
+
+## Typical chaining
+
+1. `soku ads list-ad-accounts` → pick an `account_id`.
+2. `soku ads list-dimensions` → learn valid dimension/metric slugs for that account.
+3. `soku ads query-single-dimension` / `query-multi-dimension` with the chosen
+   `--account-id` + slugs.
+
+Each command's `--help` lists related actions (`see_also`) so you can jump
+between them without re-scanning everything.