@layerarc/agent-sdk-cli 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @layerarc/agent-sdk-cli
+
+Agent-friendly command line interface for the LayerArc Agent API.
+
+The CLI is designed for coding agents and power users that need stable JSON output, non-interactive execution, and environment-only authentication.
+
+## Install
+
+```bash
+npx -y @layerarc/agent-sdk-cli projects list
+```
+
+The package exposes the `layerarc` binary.
+
+## Environment
+
+```bash
+export LAYERARC_AGENT_API_BASE_URL=https://agent.layerarc.com/v1
+export LAYERARC_AGENT_API_TOKEN=<token>
+export LAYERARC_PROJECT_ID=<optional default project id>
+```
+
+`LAYERARC_AGENT_API_TOKEN` is required for API commands. `LAYERARC_PROJECT_ID` is optional and is used as the default project id. A command-level `--project-id` value takes precedence.
+
+## Examples
+
+```bash
+npx -y @layerarc/agent-sdk-cli projects list
+npx -y @layerarc/agent-sdk-cli pages list
+npx -y @layerarc/agent-sdk-cli pages create --body page.json
+npx -y @layerarc/agent-sdk-cli pages content put --page-id 123 --file page.html
+npx -y @layerarc/agent-sdk-cli gsc url-inspection inspect --inspection-url https://example.com/page
+```
+
+## Docs And Skills
+
+```bash
+npx -y @layerarc/agent-sdk-cli docs list
+npx -y @layerarc/agent-sdk-cli docs show pages
+npx -y @layerarc/agent-sdk-cli skills list
+npx -y @layerarc/agent-sdk-cli skills show create-page
+```
+
+## Output Contract
+
+Successful commands write machine-readable JSON to stdout:
+
+```json
+{ "ok": true, "data": {} }
+```
+
+Failures use the same stable wrapper:
+
+```json
+{ "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "Set LAYERARC_AGENT_API_TOKEN." } }
+```
+
+Diagnostics are written to stderr only. The CLI does not prompt interactively and does not print tokens.

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+export type CliEnv = Record<string, string | undefined>;
+export type CliIo = {
+    env: CliEnv;
+    fetch: typeof fetch;
+    readFile: (path: string) => Promise<string>;
+    readStdin: () => Promise<string>;
+};
+export type CliResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function execute(argv: string[], io: CliIo): Promise<CliResult>;

package/dist/cli.js

@@ -0,0 +1,464 @@
+const DEFAULT_API_BASE_URL = "https://agent.layerarc.com/v1";
+const DOC_PATHS = [
+    "/docs/cli.md",
+    "/docs/cli/projects.md",
+    "/docs/cli/pipelines.md",
+    "/docs/cli/pages.md",
+    "/docs/cli/page-content.md",
+    "/docs/cli/gsc.md",
+    "/docs/cli/gsc-sites.md",
+    "/docs/cli/gsc-search-analytics.md",
+    "/docs/cli/gsc-sitemaps.md",
+    "/docs/cli/gsc-url-inspection.md",
+];
+const SKILL_PATHS = [
+    "/skills/cli.md",
+    "/skills/cli/create-page.md",
+    "/skills/cli/update-page.md",
+    "/skills/cli/attach-pipeline.md",
+    "/skills/cli/full-page-lifecycle.md",
+    "/skills/cli/gsc-select-property.md",
+    "/skills/cli/gsc-get-summary.md",
+    "/skills/cli/gsc-list-page-rows.md",
+    "/skills/cli/gsc-top-queries.md",
+    "/skills/cli/gsc-high-potential-pages.md",
+    "/skills/cli/gsc-high-potential-ranking-pages.md",
+    "/skills/cli/gsc-list-sitemaps.md",
+    "/skills/cli/gsc-submit-sitemap.md",
+    "/skills/cli/gsc-inspect-url.md",
+];
+class CliError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = 1) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+export async function execute(argv, io) {
+    try {
+        const parsed = parseArgs(argv);
+        const config = getConfig(io.env, parsed.options);
+        const data = await runCommand(parsed, config, io);
+        return {
+            exitCode: 0,
+            stdout: `${JSON.stringify({ ok: true, data })}\n`,
+            stderr: "",
+        };
+    }
+    catch (error) {
+        const normalized = normalizeError(error);
+        return {
+            exitCode: error instanceof CliError ? error.exitCode : 1,
+            stdout: `${JSON.stringify({ ok: false, error: normalized })}\n`,
+            stderr: "",
+        };
+    }
+}
+function parseArgs(argv) {
+    const command = [];
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith("--")) {
+            command.push(arg);
+            continue;
+        }
+        const withoutPrefix = arg.slice(2);
+        const equalsIndex = withoutPrefix.indexOf("=");
+        if (equalsIndex >= 0) {
+            options[withoutPrefix.slice(0, equalsIndex)] = withoutPrefix.slice(equalsIndex + 1);
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next && !next.startsWith("--")) {
+            options[withoutPrefix] = next;
+            index += 1;
+        }
+        else {
+            options[withoutPrefix] = true;
+        }
+    }
+    return {
+        command,
+        options,
+    };
+}
+function getConfig(env, options) {
+    return {
+        apiBaseUrl: env.LAYERARC_AGENT_API_BASE_URL || DEFAULT_API_BASE_URL,
+        token: env.LAYERARC_AGENT_API_TOKEN,
+        projectId: stringOption(options, "project-id") || env.LAYERARC_PROJECT_ID,
+    };
+}
+async function runCommand(parsed, config, io) {
+    const [group, name, subcommand, action] = parsed.command;
+    if (!group) {
+        throw new CliError("COMMAND_REQUIRED", "Provide a LayerArc command.");
+    }
+    if (group === "docs") {
+        return runDocsCommand(parsed, config, io);
+    }
+    if (group === "skills") {
+        return runSkillsCommand(parsed, config, io);
+    }
+    const spec = await buildApiRequest(parsed, config, io);
+    return sendApiRequest(spec, config, io.fetch);
+}
+async function buildApiRequest(parsed, config, io) {
+    const [group, name, subcommand, action] = parsed.command;
+    const options = parsed.options;
+    if (group === "projects" && name === "list") {
+        return { method: "GET", path: "/projects" };
+    }
+    if (group === "projects" && name === "get") {
+        return { method: "GET", path: `/projects/${encodeURIComponent(requireProjectId(config))}` };
+    }
+    if (group === "pipelines" && name === "get") {
+        return {
+            method: "GET",
+            path: `/projects/${encodeURIComponent(requireProjectId(config))}/pipelines/${encodeURIComponent(requireStringOption(options, "pipeline-id", "PIPELINE_ID_REQUIRED"))}`,
+        };
+    }
+    if (group === "pages") {
+        return buildPagesRequest(name, subcommand, options, config, io);
+    }
+    if (group === "gsc") {
+        return buildGscRequest(name, subcommand, action, options, config, io);
+    }
+    throw new CliError("UNKNOWN_COMMAND", `Unknown command: ${parsed.command.join(" ")}`);
+}
+async function buildPagesRequest(name, subcommand, options, config, io) {
+    const projectPath = `/projects/${encodeURIComponent(requireProjectId(config))}`;
+    if (name === "list") {
+        return {
+            method: "GET",
+            path: `${projectPath}/pages`,
+            query: pickStringOptions(options, ["limit", "offset", "language", "slug"]),
+        };
+    }
+    if (name === "create") {
+        return {
+            method: "POST",
+            path: `${projectPath}/pages`,
+            body: await readJsonBody(options, io),
+        };
+    }
+    if (name === "get") {
+        return {
+            method: "GET",
+            path: `${projectPath}/pages/${encodeURIComponent(requireStringOption(options, "page-id", "PAGE_ID_REQUIRED"))}`,
+        };
+    }
+    if (name === "update") {
+        return {
+            method: "PATCH",
+            path: `${projectPath}/pages/${encodeURIComponent(requireStringOption(options, "page-id", "PAGE_ID_REQUIRED"))}`,
+            body: await readJsonBody(options, io),
+        };
+    }
+    if (name === "delete") {
+        return {
+            method: "DELETE",
+            path: `${projectPath}/pages/${encodeURIComponent(requireStringOption(options, "page-id", "PAGE_ID_REQUIRED"))}`,
+        };
+    }
+    if (name === "content") {
+        const pagePath = `${projectPath}/pages/${encodeURIComponent(requireStringOption(options, "page-id", "PAGE_ID_REQUIRED"))}/content`;
+        if (subcommand === "get") {
+            return {
+                method: "GET",
+                path: pagePath,
+                contentType: "html",
+            };
+        }
+        if (subcommand === "put") {
+            return {
+                method: "PUT",
+                path: pagePath,
+                body: await readHtmlBody(options, io),
+                contentType: "html",
+            };
+        }
+    }
+    throw new CliError("UNKNOWN_COMMAND", "Unknown pages command.");
+}
+async function buildGscRequest(name, subcommand, action, options, config, io) {
+    const projectPath = `/projects/${encodeURIComponent(requireProjectId(config))}/gsc`;
+    if (name === "sites") {
+        if (subcommand === "list" || subcommand === "get" || subcommand === "delete") {
+            return { method: "POST", path: `${projectPath}/sites/${subcommand}`, body: {} };
+        }
+        if (subcommand === "add") {
+            return {
+                method: "POST",
+                path: `${projectPath}/sites/add`,
+                body: { siteUrl: requireStringOption(options, "site-url", "SITE_URL_REQUIRED") },
+            };
+        }
+    }
+    if (name === "search-analytics" && subcommand === "query") {
+        return {
+            method: "POST",
+            path: `${projectPath}/search-analytics/query`,
+            body: await readJsonBody(options, io),
+        };
+    }
+    if (name === "sitemaps") {
+        if (subcommand === "list") {
+            return {
+                method: "POST",
+                path: `${projectPath}/sitemaps/list`,
+                body: stringOption(options, "body") ? await readJsonBody(options, io) : {},
+            };
+        }
+        if (subcommand === "get" || subcommand === "submit" || subcommand === "delete") {
+            return {
+                method: "POST",
+                path: `${projectPath}/sitemaps/${subcommand}`,
+                body: { feedpath: requireStringOption(options, "feedpath", "FEEDPATH_REQUIRED") },
+            };
+        }
+    }
+    if (name === "url-inspection" && subcommand === "inspect") {
+        const languageCode = stringOption(options, "language-code");
+        return {
+            method: "POST",
+            path: `${projectPath}/url-inspection/inspect`,
+            body: {
+                inspectionUrl: requireStringOption(options, "inspection-url", "INSPECTION_URL_REQUIRED"),
+                ...(languageCode ? { languageCode } : {}),
+            },
+        };
+    }
+    throw new CliError("UNKNOWN_COMMAND", "Unknown GSC command.");
+}
+async function sendApiRequest(spec, config, fetchImpl) {
+    if (!config.token) {
+        throw new CliError("AUTH_REQUIRED", "Set LAYERARC_AGENT_API_TOKEN.");
+    }
+    const url = new URL(`${config.apiBaseUrl}${spec.path}`);
+    for (const [key, value] of Object.entries(spec.query || {})) {
+        if (value !== undefined) {
+            url.searchParams.set(key, value);
+        }
+    }
+    const headers = new Headers({
+        Accept: spec.contentType === "html" ? "text/html, application/json" : "application/json",
+        Authorization: `Bearer ${config.token}`,
+    });
+    let body;
+    if (spec.body !== undefined) {
+        if (spec.contentType === "html") {
+            headers.set("Content-Type", "text/html; charset=utf-8");
+            body = String(spec.body);
+        }
+        else {
+            headers.set("Content-Type", "application/json");
+            body = JSON.stringify(spec.body);
+        }
+    }
+    const response = await fetchImpl(url.toString(), {
+        method: spec.method,
+        headers,
+        body,
+    });
+    const text = await response.text();
+    const payload = parseTextPayload(text, response.headers.get("content-type") || "");
+    if (!response.ok) {
+        throw responseError(response.status, payload);
+    }
+    if (spec.contentType === "html" && typeof payload === "string") {
+        return { content: payload };
+    }
+    if (payload && typeof payload === "object" && "data" in payload) {
+        return payload.data;
+    }
+    return payload;
+}
+async function runDocsCommand(parsed, config, io) {
+    const [, action, slug] = parsed.command;
+    if (action === "list") {
+        return {
+            docs: DOC_PATHS.map((path) => pathToSlug(path, "/docs/cli/")),
+        };
+    }
+    if (action === "show") {
+        const path = docsSlugToPath(requirePositional(slug, "DOC_SLUG_REQUIRED"));
+        return {
+            path,
+            content: await fetchTemplate(path, config, io.fetch),
+        };
+    }
+    throw new CliError("UNKNOWN_COMMAND", "Unknown docs command.");
+}
+async function runSkillsCommand(parsed, config, io) {
+    const [, action, slug] = parsed.command;
+    if (action === "list") {
+        return {
+            skills: SKILL_PATHS.map((path) => pathToSlug(path, "/skills/cli/")),
+        };
+    }
+    if (action === "show") {
+        const path = skillSlugToPath(requirePositional(slug, "SKILL_SLUG_REQUIRED"));
+        return {
+            path,
+            content: await fetchTemplate(path, config, io.fetch),
+        };
+    }
+    throw new CliError("UNKNOWN_COMMAND", "Unknown skills command.");
+}
+async function fetchTemplate(path, config, fetchImpl) {
+    const origin = new URL(config.apiBaseUrl).origin;
+    const response = await fetchImpl(`${origin}/internal/docs-template${path}`, {
+        headers: {
+            Accept: "text/markdown",
+        },
+    });
+    const markdown = await response.text();
+    if (!response.ok) {
+        throw new CliError("DOCS_UNAVAILABLE", markdown || `Docs request failed with status ${response.status}.`);
+    }
+    return markdown
+        .replaceAll("{{AGENT_API_BASE_URL}}", config.apiBaseUrl)
+        .replaceAll("{{DOCS_BASE_URL}}", origin)
+        .replaceAll("{{AUTH_TOKEN}}", "<YOUR_AUTH_TOKEN>");
+}
+function docsSlugToPath(slug) {
+    const path = slugToPath(slug, "/docs/cli/");
+    if (!DOC_PATHS.includes(path)) {
+        throw new CliError("DOC_NOT_FOUND", `Unknown docs page: ${slug}`);
+    }
+    return path;
+}
+function skillSlugToPath(slug) {
+    const path = slugToPath(slug, "/skills/cli/");
+    if (!SKILL_PATHS.includes(path)) {
+        throw new CliError("SKILL_NOT_FOUND", `Unknown skill page: ${slug}`);
+    }
+    return path;
+}
+function slugToPath(slug, prefix) {
+    if (slug === "index") {
+        return prefix === "/docs/cli/" ? "/docs/cli.md" : "/skills/cli.md";
+    }
+    const normalized = slug.endsWith(".md") ? slug : `${slug}.md`;
+    if (prefix === "/docs/cli/" && (normalized === "cli.md" || normalized.startsWith("cli/"))) {
+        return `/docs/${normalized}`;
+    }
+    if (prefix === "/skills/cli/" && (normalized === "cli.md" || normalized.startsWith("cli/"))) {
+        return `/skills/${normalized}`;
+    }
+    return `${prefix}${normalized}`;
+}
+function pathToSlug(path, prefix) {
+    if (path === "/docs/cli.md" || path === "/skills/cli.md") {
+        return "index";
+    }
+    return path.slice(prefix.length).replace(/\.md$/, "");
+}
+async function readJsonBody(options, io) {
+    const path = requireStringOption(options, "body", "BODY_REQUIRED");
+    const text = await io.readFile(path);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliError("INVALID_JSON_BODY", `Body file must contain valid JSON: ${path}`);
+    }
+}
+async function readHtmlBody(options, io) {
+    const file = stringOption(options, "file");
+    const useStdin = options.stdin === true;
+    if (file && useStdin) {
+        throw new CliError("CONTENT_SOURCE_CONFLICT", "Use either --file or --stdin, not both.");
+    }
+    if (file) {
+        return io.readFile(file);
+    }
+    if (useStdin) {
+        return io.readStdin();
+    }
+    throw new CliError("CONTENT_SOURCE_REQUIRED", "Provide --file or --stdin.");
+}
+function pickStringOptions(options, names) {
+    const picked = {};
+    for (const name of names) {
+        picked[name] = stringOption(options, name);
+    }
+    return picked;
+}
+function requireProjectId(config) {
+    if (!config.projectId) {
+        throw new CliError("PROJECT_ID_REQUIRED", "Provide --project-id or set LAYERARC_PROJECT_ID.");
+    }
+    return config.projectId;
+}
+function requireStringOption(options, name, code) {
+    const value = stringOption(options, name);
+    if (!value) {
+        throw new CliError(code, `Provide --${name}.`);
+    }
+    return value;
+}
+function requirePositional(value, code) {
+    if (!value) {
+        throw new CliError(code, "Provide the required command argument.");
+    }
+    return value;
+}
+function stringOption(options, name) {
+    const value = options[name];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function parseTextPayload(text, contentType) {
+    if (!text) {
+        return null;
+    }
+    if (contentType.includes("application/json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function responseError(status, payload) {
+    if (payload && typeof payload === "object") {
+        const record = payload;
+        const code = typeof record.error?.code === "string" ? record.error.code : `HTTP_${status}`;
+        const message = typeof record.error?.message === "string"
+            ? record.error.message
+            : typeof record.message === "string"
+                ? record.message
+                : `Request failed with status ${status}.`;
+        return new CliError(code, message);
+    }
+    return new CliError(`HTTP_${status}`, typeof payload === "string" && payload ? payload : `Request failed with status ${status}.`);
+}
+function normalizeError(error) {
+    if (error instanceof CliError) {
+        return {
+            code: error.code,
+            message: error.message,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            code: "CLI_ERROR",
+            message: error.message,
+        };
+    }
+    return {
+        code: "CLI_ERROR",
+        message: "Unexpected CLI error.",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { execute } from "./cli.js";
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+const result = await execute(process.argv.slice(2), {
+    env: process.env,
+    fetch: globalThis.fetch,
+    readFile: (path) => readFile(path, "utf8"),
+    readStdin,
+});
+if (result.stderr) {
+    process.stderr.write(result.stderr);
+}
+process.stdout.write(result.stdout);
+process.exitCode = result.exitCode;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@layerarc/agent-sdk-cli",
+  "version": "0.1.0",
+  "description": "Agent-friendly command line interface for the LayerArc Agent API.",
+  "type": "module",
+  "bin": {
+    "layerarc": "dist/index.js"
+  },
+  "homepage": "https://layerarc.com/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/capgoai/capgo-v1.git",
+    "directory": "apps/layerarc-sdk-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/capgoai/capgo-v1/issues"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "layerarc",
+    "agent",
+    "cli",
+    "seo",
+    "gsc"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "bun run build",
+    "typecheck": "tsc -p tsconfig.json --pretty false --noEmit",
+    "test": "bun test src"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.5.2"
+  }
+}