@pokelo/cli 0.1.0

package/src/commands/assets.mjs

@@ -0,0 +1,283 @@
+import { createReadStream, createWriteStream, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import { resolveConfig } from '../config.mjs';
+import { EXIT_API, fail, writeJson } from '../exit.mjs';
+import { apiRequest } from '../http.mjs';
+
+/** Match API `ASSET_BASE64_UPLOAD_MAX_BYTES`. */
+const BASE64_MAX_BYTES = 8 * 1024 * 1024;
+
+const MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.json': 'application/json',
+  '.csv': 'text/csv',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+};
+
+function requireProject(config, flags) {
+  const project =
+    (typeof flags.project === 'string' && flags.project.trim()) || config.defaultProjectId;
+  if (!project) {
+    fail('project required (--project / -p, POKELO_PROJECT, or defaultProjectId in config)');
+  }
+  return project;
+}
+
+function guessMime(filePath, explicit) {
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  const ext = extname(filePath).toLowerCase();
+  return MIME_BY_EXT[ext] || 'application/octet-stream';
+}
+
+function flagStr(flags, key) {
+  return typeof flags[key] === 'string' && flags[key].trim() ? flags[key].trim() : undefined;
+}
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runAssets(positional, flags) {
+  const sub = positional[0];
+  if (!sub) {
+    fail(
+      'Usage: pokelo assets <list|get|upload|download|update|delete>\n' +
+        '  pokelo assets list [--project] [--type] [--source] [--visibility] [--document] [--page] [--limit]\n' +
+        '  pokelo assets get <asset-id> [--project]\n' +
+        '  pokelo assets upload <file> [--name] [--mime] [--visibility] [--document] [--description] [--project]\n' +
+        '  pokelo assets download <asset-id> --out <path> [--project]\n' +
+        '  pokelo assets update <asset-id> [--name] [--description] [--visibility] [--document] [--project]\n' +
+        '  pokelo assets delete <asset-id> [--project]',
+    );
+  }
+
+  const config = resolveConfig(flags);
+  const project = requireProject(config, flags);
+  const base = `/projects/${encodeURIComponent(project)}/assets`;
+
+  if (sub === 'list') {
+    const data = await apiRequest(config, 'GET', base, {
+      query: {
+        type: flagStr(flags, 'type'),
+        source: flagStr(flags, 'source'),
+        visibility: flagStr(flags, 'visibility'),
+        documentId: flagStr(flags, 'document'),
+        page: typeof flags.page === 'number' ? flags.page : undefined,
+        limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+      },
+    });
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'get') {
+    const id = positional[1];
+    if (!id) fail('Usage: pokelo assets get <asset-id> [--project <ref>]');
+    const data = await apiRequest(config, 'GET', `${base}/${encodeURIComponent(id)}`);
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'upload') {
+    const filePath = positional[1];
+    if (!filePath) fail('Usage: pokelo assets upload <file> [--project <ref>]');
+    await uploadFile(config, project, filePath, flags);
+    return;
+  }
+
+  if (sub === 'download') {
+    const id = positional[1];
+    const out = flagStr(flags, 'out');
+    if (!id || !out) {
+      fail('Usage: pokelo assets download <asset-id> --out <path> [--project <ref>]');
+    }
+    await downloadAsset(config, project, id, out);
+    return;
+  }
+
+  if (sub === 'update') {
+    const id = positional[1];
+    if (!id) fail('Usage: pokelo assets update <asset-id> [options]');
+    const body = {};
+    if (flagStr(flags, 'name')) body.name = flagStr(flags, 'name');
+    if (typeof flags.description === 'string') body.description = flags.description;
+    if (flagStr(flags, 'visibility')) body.visibility = flagStr(flags, 'visibility');
+    if (typeof flags.document === 'string') {
+      body.documentId = flags.document.trim() || null;
+    }
+    if (Object.keys(body).length === 0) {
+      fail('assets update requires at least one of --name, --description, --visibility, --document');
+    }
+    const data = await apiRequest(config, 'PATCH', `${base}/${encodeURIComponent(id)}`, { body });
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'delete') {
+    const id = positional[1];
+    if (!id) fail('Usage: pokelo assets delete <asset-id> [--project <ref>]');
+    await apiRequest(config, 'DELETE', `${base}/${encodeURIComponent(id)}`);
+    writeJson({ deleted: true, id });
+    return;
+  }
+
+  fail(`unknown assets command: ${sub}`);
+}
+
+async function uploadFile(config, project, filePath, flags) {
+  let st;
+  try {
+    st = statSync(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(`cannot read file: ${msg}`);
+  }
+  if (!st.isFile()) fail(`not a file: ${filePath}`);
+
+  const name = flagStr(flags, 'name') || basename(filePath);
+  const mimeType = guessMime(filePath, flagStr(flags, 'mime'));
+  const visibility = flagStr(flags, 'visibility');
+  const documentId = flagStr(flags, 'document');
+  const description = flagStr(flags, 'description');
+  const base = `/projects/${encodeURIComponent(project)}/assets`;
+
+  if (st.size <= BASE64_MAX_BYTES) {
+    const buf = readFileSync(filePath);
+    const body = {
+      name,
+      mimeType,
+      contentBase64: buf.toString('base64'),
+      ...(visibility ? { visibility } : {}),
+      ...(documentId ? { documentId } : {}),
+      ...(description ? { description } : {}),
+    };
+    const data = await apiRequest(config, 'POST', `${base}/base64`, { body });
+    writeJson(data);
+    return;
+  }
+
+  // Large file: init → PUT → complete
+  const init = await apiRequest(config, 'POST', `${base}/uploads`, {
+    body: {
+      name,
+      mimeType,
+      size: st.size,
+      ...(visibility ? { visibility } : {}),
+      ...(documentId ? { documentId } : {}),
+      ...(description ? { description } : {}),
+    },
+  });
+
+  const uploadUrl = init?.uploadUrl;
+  const headers = { ...(init?.headers || {}) };
+  if (!uploadUrl) fail('upload init did not return uploadUrl', EXIT_API);
+
+  let putRes;
+  try {
+    putRes = await fetch(uploadUrl, {
+      method: 'PUT',
+      headers,
+      body: createReadStream(filePath),
+      // Node fetch needs duplex when body is a stream
+      duplex: 'half',
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(`S3 PUT failed: ${msg}`, EXIT_API);
+  }
+
+  if (!putRes.ok) {
+    const t = await putRes.text().catch(() => '');
+    fail(`S3 PUT HTTP ${putRes.status}${t ? `: ${t.slice(0, 200)}` : ''}`, EXIT_API);
+  }
+
+  const assetId = init?.asset?.id;
+  if (!assetId) fail('upload init did not return asset.id', EXIT_API);
+
+  const completed = await apiRequest(
+    config,
+    'POST',
+    `${base}/${encodeURIComponent(assetId)}/complete`,
+  );
+  writeJson(completed);
+}
+
+async function downloadAsset(config, project, assetId, outPath) {
+  const asset = await apiRequest(
+    config,
+    'GET',
+    `/projects/${encodeURIComponent(project)}/assets/${encodeURIComponent(assetId)}`,
+  );
+
+  let url = asset?.downloadUrl;
+  if (!url) {
+    // Fall back to stable content redirect (follow redirects with auth on first hop).
+    const contentUrl = new URL(
+      `${config.url}/projects/${encodeURIComponent(project)}/assets/${encodeURIComponent(assetId)}/content`,
+    );
+    let res;
+    try {
+      res = await fetch(contentUrl, {
+        method: 'GET',
+        headers: { Authorization: `Bearer ${config.token}` },
+        redirect: 'manual',
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      fail(`content request failed: ${msg}`, EXIT_API);
+    }
+    if (res.status >= 300 && res.status < 400) {
+      url = res.headers.get('location');
+    } else if (res.ok && res.body) {
+      await pipeline(Readable.fromWeb(res.body), createWriteStream(outPath));
+      writeJson({
+        id: assetId,
+        name: asset?.name ?? null,
+        out: outPath,
+        bytes: statSync(outPath).size,
+      });
+      return;
+    } else {
+      fail(`cannot resolve download URL (HTTP ${res.status})`, EXIT_API);
+    }
+  }
+
+  if (!url) fail('asset has no downloadUrl (not ready or no binary)', EXIT_API);
+
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(`download failed: ${msg}`, EXIT_API);
+  }
+  if (!res.ok) fail(`download HTTP ${res.status}`, EXIT_API);
+
+  if (res.body) {
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(outPath));
+  } else {
+    const buf = Buffer.from(await res.arrayBuffer());
+    writeFileSync(outPath, buf);
+  }
+
+  writeJson({
+    id: assetId,
+    name: asset?.name ?? null,
+    out: outPath,
+    bytes: statSync(outPath).size,
+  });
+}

package/src/commands/auth.mjs

@@ -0,0 +1,109 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output, stderr } from 'node:process';
+
+import {
+  loadPersistedConfig,
+  maskToken,
+  normalizeApiBaseUrl,
+  saveConfig,
+  xdgConfigPath,
+} from '../config.mjs';
+import { fail, writeJson } from '../exit.mjs';
+
+async function readTokenStdin() {
+  const chunks = [];
+  for await (const chunk of input) {
+    chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+  }
+  return chunks.join('').trim();
+}
+
+async function promptLogin() {
+  if (!input.isTTY) {
+    fail('interactive login requires a TTY; use --url and --token (or --token-stdin)');
+  }
+  const rl = createInterface({ input, output: stderr });
+  try {
+    const url = (await rl.question('Pokelo URL (e.g. https://pokelo.example.com): ')).trim();
+    const token = (await rl.question('Personal Access Token: ')).trim();
+    return { url, token };
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runAuth(positional, flags) {
+  const sub = positional[0];
+  if (!sub || sub === 'help') {
+    fail(
+      'Usage: pokelo auth <login|status>\n' +
+        '  pokelo auth login --url <url> --token <token>\n' +
+        '  pokelo auth login --url <url> --token-stdin\n' +
+        '  pokelo auth login\n' +
+        '  pokelo auth status',
+    );
+  }
+
+  if (sub === 'status') {
+    const file = loadPersistedConfig();
+    const envUrl = process.env.POKELO_URL?.trim() || null;
+    const envToken = process.env.POKELO_TOKEN?.trim() || null;
+    const url = envUrl || file?.url || null;
+    const token = envToken || file?.token || null;
+    writeJson({
+      configured: Boolean(url && token),
+      url: url ? normalizeApiBaseUrl(url) : null,
+      tokenSet: Boolean(token),
+      tokenPreview: token ? maskToken(token) : null,
+      defaultProjectId: process.env.POKELO_PROJECT?.trim() || file?.defaultProjectId || null,
+      configPath: xdgConfigPath(),
+      sources: {
+        url: envUrl ? 'env' : file?.url ? 'file' : null,
+        token: envToken ? 'env' : file?.token ? 'file' : null,
+      },
+    });
+    return;
+  }
+
+  if (sub === 'login') {
+    let url = typeof flags.url === 'string' ? flags.url.trim() : '';
+    let token = typeof flags.token === 'string' ? flags.token.trim() : '';
+    const tokenStdin = flags.tokenStdin === true;
+
+    if (tokenStdin) {
+      token = await readTokenStdin();
+    }
+
+    if (!url || !token) {
+      if (!url && !token && !tokenStdin && input.isTTY) {
+        const prompted = await promptLogin();
+        url = url || prompted.url;
+        token = token || prompted.token;
+      }
+    }
+
+    if (!url) fail('url is required (--url or interactive prompt)');
+    if (!token) fail('token is required (--token, --token-stdin, or interactive prompt)');
+
+    const existing = loadPersistedConfig();
+    const path = saveConfig({
+      url,
+      token,
+      defaultProjectId: existing?.defaultProjectId ?? null,
+    });
+    writeJson({
+      ok: true,
+      configPath: path,
+      url: normalizeApiBaseUrl(url),
+      tokenSet: true,
+      tokenPreview: maskToken(token),
+    });
+    return;
+  }
+
+  fail(`unknown auth command: ${sub}`);
+}

package/src/commands/docs.mjs

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs';
+
+import { resolveConfig } from '../config.mjs';
+import { fail, writeJson } from '../exit.mjs';
+import { apiRequest } from '../http.mjs';
+
+function requireProject(config, flags) {
+  const project =
+    (typeof flags.project === 'string' && flags.project.trim()) || config.defaultProjectId;
+  if (!project) {
+    fail('project required (--project / -p, POKELO_PROJECT, or defaultProjectId in config)');
+  }
+  return project;
+}
+
+function resolveContent(flags) {
+  if (typeof flags.contentFile === 'string' && flags.contentFile.trim()) {
+    try {
+      return readFileSync(flags.contentFile.trim(), 'utf8');
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      fail(`cannot read --content-file: ${msg}`);
+    }
+  }
+  if (typeof flags.content === 'string') return flags.content;
+  return undefined;
+}
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runDocs(positional, flags) {
+  const sub = positional[0];
+  if (!sub) {
+    fail(
+      'Usage: pokelo docs <list|get|create|update>\n' +
+        '  pokelo docs list [--project <ref>]\n' +
+        '  pokelo docs get <id-or-slug> [--project <ref>]\n' +
+        '  pokelo docs create --title <t> [--type] [--content|--content-file] [--parent] [--project]\n' +
+        '  pokelo docs update <id-or-slug> [--title] [--content|--content-file] [--project]',
+    );
+  }
+
+  const config = resolveConfig(flags);
+  const project = requireProject(config, flags);
+
+  if (sub === 'list') {
+    const data = await apiRequest(
+      config,
+      'GET',
+      `/projects/${encodeURIComponent(project)}/documents`,
+      {
+        query: {
+          page: typeof flags.page === 'number' ? flags.page : undefined,
+          limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+          parentId: typeof flags.parent === 'string' ? flags.parent : undefined,
+          tree: flags.tree === true ? 'true' : undefined,
+        },
+      },
+    );
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'get') {
+    const docRef = positional[1];
+    if (!docRef) fail('Usage: pokelo docs get <document-id-or-slug> [--project <ref>]');
+    const data = await apiRequest(
+      config,
+      'GET',
+      `/projects/${encodeURIComponent(project)}/documents/${encodeURIComponent(docRef)}`,
+    );
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'create') {
+    const title = typeof flags.title === 'string' ? flags.title.trim() : '';
+    if (!title) fail('docs create requires --title');
+    const contentMd = resolveContent(flags);
+    const body = {
+      title,
+      ...(typeof flags.type === 'string' && flags.type.trim()
+        ? { type: flags.type.trim() }
+        : {}),
+      ...(contentMd !== undefined ? { contentMd } : {}),
+      ...(typeof flags.parent === 'string' && flags.parent.trim()
+        ? { parentId: flags.parent.trim() }
+        : {}),
+      ...(typeof flags.status === 'string' && flags.status.trim()
+        ? { status: flags.status.trim() }
+        : {}),
+    };
+    const data = await apiRequest(
+      config,
+      'POST',
+      `/projects/${encodeURIComponent(project)}/documents`,
+      { body },
+    );
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'update') {
+    const docRef = positional[1];
+    if (!docRef) fail('Usage: pokelo docs update <document-id-or-slug> [options]');
+    const contentMd = resolveContent(flags);
+    const body = {};
+    if (typeof flags.title === 'string' && flags.title.trim()) body.title = flags.title.trim();
+    if (contentMd !== undefined) body.contentMd = contentMd;
+    if (typeof flags.type === 'string' && flags.type.trim()) body.type = flags.type.trim();
+    if (typeof flags.status === 'string' && flags.status.trim()) body.status = flags.status.trim();
+    if (typeof flags.parent === 'string') {
+      body.parentId = flags.parent.trim() || null;
+    }
+    if (Object.keys(body).length === 0) {
+      fail('docs update requires at least one of --title, --content, --content-file, --type, --status, --parent');
+    }
+    const data = await apiRequest(
+      config,
+      'PATCH',
+      `/projects/${encodeURIComponent(project)}/documents/${encodeURIComponent(docRef)}`,
+      { body },
+    );
+    writeJson(data);
+    return;
+  }
+
+  fail(`unknown docs command: ${sub}`);
+}

package/src/commands/projects.mjs

@@ -0,0 +1,35 @@
+import { resolveConfig } from '../config.mjs';
+import { fail, writeJson } from '../exit.mjs';
+import { apiRequest } from '../http.mjs';
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runProjects(positional, flags) {
+  const sub = positional[0];
+  const config = resolveConfig(flags);
+
+  if (sub === 'list' || !sub) {
+    const data = await apiRequest(config, 'GET', '/projects', {
+      query: {
+        page: typeof flags.page === 'number' ? flags.page : undefined,
+        limit: typeof flags.limit === 'number' ? flags.limit : undefined,
+        q: typeof flags.search === 'string' ? flags.search : undefined,
+        status: typeof flags.status === 'string' ? flags.status : undefined,
+      },
+    });
+    writeJson(data);
+    return;
+  }
+
+  if (sub === 'get') {
+    const ref = positional[1];
+    if (!ref) fail('Usage: pokelo projects get <project-id-or-slug>');
+    const data = await apiRequest(config, 'GET', `/projects/${encodeURIComponent(ref)}`);
+    writeJson(data);
+    return;
+  }
+
+  fail(`unknown projects command: ${sub}\nUsage: pokelo projects <list|get>`);
+}

package/src/commands/search.mjs

@@ -0,0 +1,36 @@
+import { resolveConfig } from '../config.mjs';
+import { fail, writeJson } from '../exit.mjs';
+import { apiRequest } from '../http.mjs';
+
+function requireProject(config, flags) {
+  const project =
+    (typeof flags.project === 'string' && flags.project.trim()) || config.defaultProjectId;
+  if (!project) {
+    fail('project required (--project / -p, POKELO_PROJECT, or defaultProjectId in config)');
+  }
+  return project;
+}
+
+/**
+ * @param {string[]} positional
+ * @param {Record<string, unknown>} flags
+ */
+export async function runSearch(positional, flags) {
+  const query = positional[0];
+  if (!query) fail('Usage: pokelo search "<query>" [--project <ref>] [--limit <n>]');
+  const config = resolveConfig(flags);
+  const project = requireProject(config, flags);
+  const limit = typeof flags.limit === 'number' ? flags.limit : undefined;
+  const data = await apiRequest(
+    config,
+    'POST',
+    `/projects/${encodeURIComponent(project)}/documents/search`,
+    {
+      body: {
+        query,
+        ...(limit !== undefined ? { limit } : {}),
+      },
+    },
+  );
+  writeJson(data);
+}