@zeyos/cli 0.2.0 → 0.4.0

package/README.md

@@ -72,6 +72,20 @@ For larger or reusable filters, put the JSON in a file:
 zeyos list tickets --filter-file ./filters/open-tickets.json --json
 ```
 
+Inspect dynamic schema definitions:
+
+```bash
+zeyos count customfields --json
+zeyos list customfields --fields ID,name,identifier,context,type --json
+```
+
+Inspect actionsteps/time-entry evidence and ticket mail:
+
+```bash
+zeyos list actionsteps --fields ID,name,status,date,duedate,effort,ticket,account --json
+zeyos list messages --fields ID,date,mailbox,subject,sender_email,to_email,ticket,reference --filter '{"ticket":42}' --json
+```
+
 Create, update, and delete:
 
 ```bash
@@ -91,6 +105,6 @@ zeyos delete ticket 42
 
 ## Coverage Boundary
 
-The CLI intentionally covers a curated registry instead of the full API surface. Use `zeyos resources` to see the supported set.
+The CLI intentionally covers a curated registry instead of the full API surface. It includes operational resources such as tickets, tasks, messages, and actionsteps; use `zeyos resources` to see the supported set.
 
 When you need unsupported resources or low-level request control, switch to [`@zeyos/client`](../docs/02-javascript-client/01-getting-started.md) and follow the escalation guidance in [CLI Coverage and Escalation](../docs/04-agent-workflows/03-cli-coverage-and-escalation.md).

package/bin/zeyos.mjs

@@ -51,11 +51,14 @@ ${_c.bold('Commands:')}
   ${_c.cyan('describe')} <resource>  Show a resource's fields, types and enums
   ${_c.cyan('doctor')} agent         Check local CLI readiness for coding agents
   ${_c.cyan('skills')} <command>     List / show / install ZeyOS agent skills
+  ${_c.cyan('okf')} <command>        List / show / check / export the OKF knowledge bundle
+  ${_c.cyan('profile')} <command>    Manage credential profiles / switch instances
 
 ${_c.bold('Global options:')}
   --json               Output as JSON
   --yaml               Output as YAML
   --query              Print the API route + JSON payload without sending it
+  --profile <name>     Use a named credential profile for this command
   --no-color           Disable ANSI colors
   -h, --help           Show help for a command
   -v, --version        Print the CLI version and exit
@@ -82,6 +85,7 @@ const OPTIONS = {
   'yaml':       { type: 'boolean' },
   'no-color':   { type: 'boolean' },
   'query':      { type: 'boolean' },
+  'profile':    { type: 'string' },
   // login
   'base-url':   { type: 'string' },
   'client-id':  { type: 'string' },
@@ -117,6 +121,10 @@ const OPTIONS = {
   'target':     { type: 'string' },
   'dir':        { type: 'string' },
   'no-logo':    { type: 'boolean' },
+  // okf
+  'out':        { type: 'string' },
+  // profile
+  'from-current': { type: 'boolean' },
 };
 
 // ── Command registry ──────────────────────────────────────────────────────────
@@ -142,6 +150,9 @@ const COMMANDS = {
   doctor:    '../commands/doctor.mjs',
   skills:    '../commands/skills.mjs',
   skill:     '../commands/skills.mjs',
+  okf:       '../commands/okf.mjs',
+  profile:   '../commands/profile.mjs',
+  profiles:  '../commands/profile.mjs',
 };
 
 // ── Per-command flag allow-lists ────────────────────────────────────────────────
@@ -149,8 +160,10 @@ const COMMANDS = {
 // immediately instead of being silently ignored. `create`/`update` are the
 // exception: they accept arbitrary `--<field>` flags, marked with `null` below.
 
-const ALWAYS_FLAGS = ['help', 'json', 'yaml', 'no-color'];
+const ALWAYS_FLAGS = ['help', 'json', 'yaml', 'no-color', 'profile'];
 const SKILLS_FLAGS = ['target', 'dir', 'global', 'local', 'force', 'yes', 'no-logo'];
+const OKF_FLAGS    = ['dir', 'out', 'force', 'no-logo'];
+const PROFILE_FLAGS = ['base-url', 'client-id', 'secret', 'local', 'from-current'];
 const DELETE_FLAGS = ['force', 'query'];
 const GET_FLAGS    = ['fields', 'extdata', 'tags', 'expand', 'all', 'query'];
 
@@ -174,6 +187,9 @@ const COMMAND_FLAGS = {
   doctor:    [],
   skills:    SKILLS_FLAGS,
   skill:     SKILLS_FLAGS,
+  okf:       OKF_FLAGS,
+  profile:   PROFILE_FLAGS,
+  profiles:  PROFILE_FLAGS,
 };
 
 // ── Main ──────────────────────────────────────────────────────────────────────

package/commands/count.mjs

@@ -51,7 +51,7 @@ export async function run(values, positional) {
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
   if (await maybeDryRun(clientState, res.list, body, values)) return;
 
   const result = await callApi(clientState, res.list, body);

package/commands/create.mjs

@@ -48,7 +48,7 @@ export async function run(values, positional) {
   // (optional) JSON body some callers pass positionally instead of via --data.
   const data = buildRecordPayload(values, positional[1]);
 
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
 
   // ── Call API ───────────────────────────────────────────────────────────────
   if (await maybeDryRun(clientState, res.create, data, values)) return;

package/commands/delete.mjs

@@ -37,7 +37,7 @@ export async function run(values, positional) {
   const res = requireResource(resourceName, 'zeyos delete <resource> <id>', 'delete', 'deletion');
   requireRecordId(id, 'zeyos delete <resource> <id>');
 
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
 
   // ── Dry run ────────────────────────────────────────────────────────────────
   // Show the request without prompting or deleting anything.

package/commands/get.mjs

@@ -68,7 +68,7 @@ export async function run(values, positional) {
   requireRecordId(id, 'zeyos get <resource> <id>');
 
   const resName = canonicalName(resourceName);
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
 
   // ── Build params ───────────────────────────────────────────────────────────
   // GET endpoints use query parameters like ?extdata=1&tags=1 to include

package/commands/list.mjs

@@ -116,7 +116,7 @@ export async function run(values, positional) {
   }
 
   // ── Call API ───────────────────────────────────────────────────────────────
-  const clientState = buildCliClient();
+  const clientState = buildCliClient(values);
   if (await maybeDryRun(clientState, res.list, body, values)) return;
 
   const fn = requireApiMethod(clientState, res.list);

package/commands/login.mjs

@@ -20,7 +20,7 @@
 
 import { createInterface }                from 'node:readline';
 import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
-import { saveConfig, loadConfig }         from '../lib/config.mjs';
+import { saveConfig, loadConfig, getProfile, upsertProfile, setActiveProfile } from '../lib/config.mjs';
 import { waitForCallback, callbackUri, BrowserUnavailableError } from '../lib/login-server.mjs';
 import { success, error, info, warn }     from '../lib/output.mjs';
 
@@ -35,6 +35,7 @@ Options:
   --base-url <url>    ZeyOS platform URL  (prompted if missing)
   --client-id <id>    OAuth client ID     (prompted if missing)
   --secret <secret>   OAuth client secret (prompted if missing)
+  --profile <name>    Store credentials/tokens in a named profile and activate it
   --scope <scope>     OAuth scope  (default: all)
   --port <port>       Local callback server port  (default: 9005)
   --global            Store credentials globally (~/.config/zeyos/credentials.json)
@@ -45,12 +46,21 @@ Options:
 `;
 
 export async function run(values) {
+  const profileName = values.profile || null;
   const scope = values.global ? 'global' : 'local';
   const port  = values.port ? Number(values.port) : DEFAULT_CALLBACK_PORT;
   const redirectUri = callbackUri(port);
 
+  // Persist either into a named profile or the legacy local/global credential file.
+  const persist = (updates) => {
+    if (profileName) upsertProfile(profileName, updates);
+    else saveConfig(updates, scope);
+  };
+
   // ── Resolve connection params ──────────────────────────────────────────────
-  const existing = values.clean ? {} : loadConfig();
+  const existing = values.clean
+    ? {}
+    : (profileName ? (getProfile(profileName) || {}) : loadConfig());
   if (values.clean) values.force = true;
 
   let baseUrl      = values['base-url']    ?? existing.baseUrl;
@@ -79,12 +89,17 @@ export async function run(values) {
   }
 
   // Save connection params immediately so they are available on retries
-  saveConfig({ baseUrl, clientId, clientSecret }, scope);
+  persist({ baseUrl, clientId, clientSecret });
 
   // ── Check if already authenticated ────────────────────────────────────────
   if (existing.accessToken && !values.force) {
-    warn('Already logged in.  Use --force to re-authenticate.');
-    return;
+    if (_tokenExpired(existing)) {
+      info('Stored access token has expired — re-authenticating…');
+    } else {
+      const where = profileName ? `profile "${profileName}"` : 'this scope';
+      warn(`Already logged in (${where}).  Use --force to re-authenticate.`);
+      return;
+    }
   }
 
   // ── Build a temporary client (no token yet) ────────────────────────────────
@@ -138,7 +153,7 @@ export async function run(values) {
     info('Exchanging authorization code for tokens…');
     const tokenSet = await client.oauth2.exchangeAuthorizationCode({ code, redirectUri });
 
-    saveConfig({
+    persist({
       baseUrl,
       clientId,
       clientSecret,
@@ -146,9 +161,12 @@ export async function run(values) {
       refreshToken:          tokenSet.refreshToken          ?? undefined,
       expiresAt:             tokenSet.expiresAt             ?? undefined,
       refreshTokenExpiresAt: tokenSet.refreshTokenExpiresAt ?? undefined,
-    }, scope);
+    });
 
-    success('Logged in successfully.');
+    if (profileName) setActiveProfile(profileName);
+    success(profileName
+      ? `Logged in — profile "${profileName}" is now active.`
+      : 'Logged in successfully.');
   } catch (err) {
     error(`Token exchange failed: ${err.message}`);
     process.exit(1);
@@ -157,6 +175,13 @@ export async function run(values) {
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
+/** True when stored creds carry an access token whose expiry is in the past. */
+function _tokenExpired(creds) {
+  if (!creds?.accessToken || creds.expiresAt == null) return false;
+  const exp = Number(creds.expiresAt) > 2e10 ? Number(creds.expiresAt) / 1000 : Number(creds.expiresAt);
+  return Number.isFinite(exp) && exp < Math.floor(Date.now() / 1000);
+}
+
 /**
  * Try the browser + callback server flow.
  * On any failure, fall back to prompting the user for the code.

package/commands/logout.mjs

@@ -10,7 +10,7 @@
  */
 
 import { createZeyosClient, MemoryTokenStore } from '@zeyos/client';
-import { loadConfig, clearTokens }             from '../lib/config.mjs';
+import { loadConfigWithSource, clearTokens, clearTokensForSource } from '../lib/config.mjs';
 import { success, warn, info }                 from '../lib/output.mjs';
 
 export const USAGE = `\
@@ -19,13 +19,13 @@ Usage: zeyos logout [options]
 Revoke the current session and clear stored tokens.
 
 Options:
-  --global    Target the global credentials file
-  -h, --help  Show this help
+  --profile <name>  Log out of a specific profile
+  --global          Target the legacy global credentials file
+  -h, --help        Show this help
 `;
 
 export async function run(values) {
-  const scope  = values.global ? 'global' : 'local';
-  const config = loadConfig();
+  const { config, source } = loadConfigWithSource({ profile: values.profile });
 
   if (!config.accessToken) {
     warn('Not currently logged in.');
@@ -58,6 +58,11 @@ export async function run(values) {
     }
   }
 
-  clearTokens(scope);
-  success('Logged out.');
+  if (values.global) {
+    clearTokens('global');
+  } else {
+    clearTokensForSource(source);
+  }
+  const where = source?.kind === 'profile' ? `profile "${source.name}"` : (values.global ? 'global credentials' : 'local credentials');
+  success(`Logged out (${where}).`);
 }

package/commands/okf.mjs

@@ -0,0 +1,192 @@
+/**
+ * zeyos okf <list|show|check|build|export>
+ *
+ * Work with the Open Knowledge Format (OKF v0.1) bundle that ships with
+ * @zeyos/client (under okf/): a directory of Markdown concept docs describing the
+ * ZeyOS data model (entities, schema, foreign keys, enums, indexes, operations)
+ * plus curated metrics, playbooks, and query concepts. Consumers — coding agents,
+ * viewers, search — read it; this command lists/shows/validates the shipped bundle
+ * and can synthesize or export one.
+ */
+
+import { readFileSync, existsSync, cpSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+import { loadOkfBundle, validateOkfFiles, buildOkf, OKF_VERSION } from '@zeyos/client';
+import { outputMode, printJson, printYaml, printTable, colors, success, error, info, warn } from '../lib/output.mjs';
+
+const require = createRequire(import.meta.url);
+
+export const USAGE = `\
+Usage: zeyos okf <command> [options]
+
+Commands:
+  list                       List concepts in the OKF bundle (type, id, title)
+  show <concept>             Print a concept doc (e.g. "tickets" or "entities/tickets")
+  check                      Validate the bundle for OKF v0.1 conformance
+  build [--out <dir>]        Synthesize an OKF bundle from the client's schema
+  export [--out <dir>]       Copy the shipped okf/ bundle into a directory
+
+Options:
+  --dir <path>               Read from an explicit bundle directory (list/show/check)
+  --out <path>               Write to this directory (build/export; default ./okf)
+  --force                    Overwrite an existing target (export)
+  --json                     Output as JSON
+  --yaml                     Output as YAML
+  -h, --help                 Show this help
+
+Examples:
+  zeyos okf list
+  zeyos okf show tickets
+  zeyos okf check
+  zeyos okf export --out ./vendor/okf
+  zeyos okf build --out ./okf-live`;
+
+// Locate the okf/ bundle shipped inside the @zeyos/client package (mirrors the
+// skills command's findAgentsDir).
+function findOkfDir() {
+  let entry;
+  try {
+    entry = require.resolve('@zeyos/client');
+  } catch {
+    return null;
+  }
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, 'okf');
+    if (existsSync(path.join(candidate, 'index.md'))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function expandHome(p) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(homedir(), p.slice(2));
+  return p;
+}
+
+function displayPath(abs) {
+  const rel = path.relative(process.cwd(), abs);
+  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) return rel;
+  const home = homedir();
+  if (abs === home || abs.startsWith(home + path.sep)) return '~' + abs.slice(home.length);
+  return abs;
+}
+
+function resolveInputDir(values) {
+  if (values.dir) return path.resolve(expandHome(values.dir));
+  const found = findOkfDir();
+  if (!found) {
+    error('Could not locate the bundled OKF bundle (the @zeyos/client okf/ directory). Pass --dir <path>.');
+    process.exit(1);
+  }
+  return found;
+}
+
+function conceptsToRows(concepts) {
+  return Object.entries(concepts)
+    .map(([id, { frontmatter }]) => ({ type: frontmatter.type || '(none)', concept: id, title: frontmatter.title || '' }))
+    .sort((a, b) => a.concept.localeCompare(b.concept));
+}
+
+async function runList(values) {
+  const dir = resolveInputDir(values);
+  const { version, concepts } = await loadOkfBundle(dir);
+  const rows = conceptsToRows(concepts);
+  const mode = outputMode(values);
+  if (mode === 'json') return printJson({ version, concepts: rows });
+  if (mode === 'yaml') return printYaml({ version, concepts: rows });
+  printTable(rows, ['type', 'concept', 'title']);
+  info(`OKF v${version || OKF_VERSION} — ${rows.length} concepts in ${displayPath(dir)}. Show one with: zeyos okf show <concept>`);
+}
+
+function runShow(values, name) {
+  const dir = resolveInputDir(values);
+  const candidates = [name, `${name}.md`, `entities/${name}.md`, path.join(dir, name), path.join(dir, `${name}.md`), path.join(dir, 'entities', `${name}.md`)];
+  for (const candidate of candidates) {
+    const abs = path.isAbsolute(candidate) ? candidate : path.join(dir, candidate);
+    if (existsSync(abs)) {
+      process.stdout.write(readFileSync(abs, 'utf8'));
+      return;
+    }
+  }
+  error(`Unknown concept "${name}". Run "zeyos okf list".`);
+  process.exit(1);
+}
+
+async function runCheck(values) {
+  const dir = resolveInputDir(values);
+  const { files } = await loadOkfBundle(dir);
+  const result = validateOkfFiles(files);
+  const mode = outputMode(values);
+  if (mode === 'json') { printJson(result); process.exit(result.valid ? 0 : 1); }
+  if (mode === 'yaml') { printYaml(result); process.exit(result.valid ? 0 : 1); }
+  if (result.valid) {
+    success(`OKF bundle is conformant: ${result.conceptCount} concepts, 0 errors (${displayPath(dir)}).`);
+    return;
+  }
+  for (const err of result.errors) error(`${err.path}: ${err.message}`);
+  error(`OKF bundle is NOT conformant: ${result.errors.length} error(s).`);
+  process.exit(1);
+}
+
+function writeBundle(outDir, files) {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(outDir, rel);
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, content, 'utf8');
+  }
+}
+
+function runBuild(values) {
+  const outDir = path.resolve(expandHome(values.out || 'okf'));
+  const files = buildOkf();
+  writeBundle(outDir, files);
+  const mode = outputMode(values);
+  const summary = { out: outDir, files: Object.keys(files).length };
+  if (mode === 'json') return printJson(summary);
+  if (mode === 'yaml') return printYaml(summary);
+  success(`Synthesized ${summary.files} OKF files → ${displayPath(outDir)}`);
+  info('This is the runtime projection from the client schema (structural only). The shipped okf/ bundle adds curated metrics, playbooks, and notes.');
+}
+
+function runExport(values) {
+  const dir = resolveInputDir(values);
+  const outDir = path.resolve(expandHome(values.out || 'okf'));
+  if (existsSync(outDir) && !values.force) {
+    if (path.resolve(dir) === outDir) {
+      warn(`Source and target are the same (${displayPath(outDir)}); nothing to do.`);
+      return;
+    }
+    error(`Target ${displayPath(outDir)} already exists. Use --force to overwrite.`);
+    process.exit(1);
+  }
+  cpSync(dir, outDir, { recursive: true });
+  const mode = outputMode(values);
+  const summary = { from: dir, out: outDir };
+  if (mode === 'json') return printJson(summary);
+  if (mode === 'yaml') return printYaml(summary);
+  success(`Exported OKF bundle → ${displayPath(outDir)}`);
+}
+
+export async function run(values, positional = []) {
+  const sub = positional[0] || 'list';
+  const rest = positional.slice(1);
+  switch (sub) {
+    case 'list': return runList(values);
+    case 'show':
+      if (!rest[0]) { error('Usage: zeyos okf show <concept>'); process.exit(1); }
+      return runShow(values, rest[0]);
+    case 'check': return runCheck(values);
+    case 'build': return runBuild(values);
+    case 'export': return runExport(values);
+    default:
+      error(`Unknown okf command "${sub}".\n\n${USAGE}`);
+      process.exit(1);
+  }
+}