clipy-kit 0.1.0

package/dist/run.d.ts

@@ -0,0 +1,353 @@
+import type { Command } from 'commander';
+export type Globals = {
+    pretty: boolean;
+    account?: string;
+    spreadsheet?: string;
+    dryRun: boolean;
+    json?: boolean;
+};
+export declare function takeGlobals(cmd: Command): Globals;
+export declare function opsFor(account?: string): {
+    getSpreadsheet: (id: string, fields?: string) => Promise<import("./lib/types.js").Spreadsheet>;
+    findSpreadsheets: (name: string, limit?: number) => Promise<{
+        query: string;
+        files: {
+            id: string;
+            name: string;
+            url: string;
+        }[];
+    }>;
+    info: (id: string) => Promise<{
+        spreadsheetId: string;
+        title: string | undefined;
+        url: string | undefined;
+        tabs: {
+            sheetId: number | undefined;
+            title: string | undefined;
+            index: number | undefined;
+            rows: number | undefined;
+            columns: number | undefined;
+        }[];
+    }>;
+    listTabs: (id: string) => Promise<{
+        title: string | undefined;
+        tabs: {
+            sheetId: number | undefined;
+            title: string | undefined;
+            index: number | undefined;
+            rows: number | undefined;
+            columns: number | undefined;
+        }[];
+    }>;
+    readTable: (id: string, opts: import("./lib/ops.js").ReadOpts) => Promise<{
+        range: string;
+        values: unknown[][];
+    } | {
+        headers: string[];
+        rows: Record<string, unknown>[];
+        headerRow: number;
+        range: string;
+        values?: undefined;
+    }>;
+    readRange: (id: string, range: string) => Promise<{
+        range: string;
+        values: unknown[][];
+    }>;
+    append: (id: string, opts: import("./lib/ops.js").WriteTableOpts) => Promise<{
+        dryRun: boolean;
+        tab: string;
+        headers: string[];
+        rows: number;
+        bootstrap: boolean;
+        result?: undefined;
+    } | {
+        tab: string;
+        headers: string[];
+        rows: number;
+        bootstrap: boolean;
+        result: unknown;
+        dryRun?: undefined;
+    } | {
+        dryRun: boolean;
+        tab: string;
+        headers: string[];
+        rows: number;
+        bootstrap?: undefined;
+        result?: undefined;
+    } | {
+        tab: string;
+        headers: string[];
+        rows: number;
+        result: unknown;
+        dryRun?: undefined;
+        bootstrap?: undefined;
+    }>;
+    update: (id: string, opts: import("./lib/ops.js").UpdateOpts) => Promise<{
+        dryRun: boolean;
+        matchedRows: unknown[];
+        set: Record<string, unknown>;
+        updated?: undefined;
+        result?: undefined;
+    } | {
+        matchedRows: unknown[];
+        updated: number;
+        result: unknown;
+        dryRun?: undefined;
+        set?: undefined;
+    }>;
+    upsert: (id: string, opts: import("./lib/ops.js").UpsertOpts) => Promise<{
+        updated: number;
+        inserted: number;
+        updatedRows: unknown[];
+        appendResult: unknown;
+    }>;
+    setRange: (id: string, opts: import("./lib/ops.js").SetOpts) => Promise<{
+        dryRun: boolean;
+        range: string;
+        values: unknown[][];
+        result?: undefined;
+    } | {
+        range: string;
+        result: unknown;
+        dryRun?: undefined;
+        values?: undefined;
+    }>;
+    clear: (id: string, range: string, dryRun?: boolean) => Promise<{
+        dryRun: boolean;
+        range: string;
+        result?: undefined;
+    } | {
+        range: string;
+        result: unknown;
+        dryRun?: undefined;
+    }>;
+    batch: (id: string, ops: import("./lib/ops.js").BatchOp[], dryRun?: boolean) => Promise<{
+        count: number;
+        results: ({
+            op: "append";
+            result: {
+                dryRun: boolean;
+                tab: string;
+                headers: string[];
+                rows: number;
+                bootstrap: boolean;
+                result?: undefined;
+            } | {
+                tab: string;
+                headers: string[];
+                rows: number;
+                bootstrap: boolean;
+                result: unknown;
+                dryRun?: undefined;
+            } | {
+                dryRun: boolean;
+                tab: string;
+                headers: string[];
+                rows: number;
+                bootstrap?: undefined;
+                result?: undefined;
+            } | {
+                tab: string;
+                headers: string[];
+                rows: number;
+                result: unknown;
+                dryRun?: undefined;
+                bootstrap?: undefined;
+            };
+        } | {
+            op: "updateKey";
+            result: {
+                dryRun: boolean;
+                matchedRows: unknown[];
+                set: Record<string, unknown>;
+                updated?: undefined;
+                result?: undefined;
+            } | {
+                matchedRows: unknown[];
+                updated: number;
+                result: unknown;
+                dryRun?: undefined;
+                set?: undefined;
+            };
+        } | {
+            op: "updateRow";
+            result: {
+                dryRun: boolean;
+                row: number;
+                set: Record<string, unknown>;
+                result?: undefined;
+            } | {
+                row: number;
+                result: unknown;
+                dryRun?: undefined;
+                set?: undefined;
+            };
+        } | {
+            op: "setRange";
+            result: {
+                dryRun: boolean;
+                range: string;
+                values: unknown[][];
+                result?: undefined;
+            } | {
+                range: string;
+                result: unknown;
+                dryRun?: undefined;
+                values?: undefined;
+            };
+        } | {
+            op: "clear";
+            result: {
+                dryRun: boolean;
+                range: string;
+                result?: undefined;
+            } | {
+                range: string;
+                result: unknown;
+                dryRun?: undefined;
+            };
+        })[];
+    }>;
+    create: (opts: import("./lib/ops.js").CreateOpts) => Promise<{
+        properties: {
+            title: string;
+        };
+        sheets: {
+            properties: {
+                title: string;
+                index: number;
+            };
+        }[];
+        dryRun: boolean;
+        spreadsheetId?: undefined;
+        url?: undefined;
+        title?: undefined;
+        tabs?: undefined;
+    } | {
+        spreadsheetId: string;
+        url: string;
+        title: string | undefined;
+        tabs: string[];
+    }>;
+    tabAdd: (id: string, opts: import("./lib/ops.js").TabAddOpts) => Promise<{
+        title: string;
+        result: unknown;
+    }>;
+    tabRename: (id: string, opts: import("./lib/ops.js").TabRenameOpts) => Promise<{
+        from: string;
+        title: string;
+        result: unknown;
+    }>;
+    tabDelete: (id: string, opts: {
+        tab: string;
+        dryRun?: boolean;
+    }) => Promise<{
+        tab: string;
+        sheetId: number;
+        result: unknown;
+    }>;
+    tabDuplicate: (id: string, opts: import("./lib/ops.js").TabDupOpts) => Promise<{
+        tab: string;
+        title: string | undefined;
+        result: unknown;
+    }>;
+    format: (id: string, opts: import("./lib/ops.js").FormatOpts) => Promise<{
+        dryRun: boolean;
+        range: string;
+        requests: Record<string, unknown>[];
+        result?: undefined;
+    } | {
+        range: string;
+        result: unknown;
+        dryRun?: undefined;
+        requests?: undefined;
+    }>;
+    formatHeader: (id: string, opts: import("./lib/ops.js").HeaderFormatOpts) => Promise<{
+        tab: string;
+        freeze: boolean;
+        result: unknown;
+    }>;
+    freeze: (id: string, opts: import("./lib/ops.js").FreezeOpts) => Promise<{
+        tab: string;
+        rows: number;
+        columns: number | undefined;
+        result: unknown;
+    }>;
+    numberFormat: (id: string, opts: import("./lib/ops.js").NumberFormatOpts) => Promise<{
+        dryRun: boolean;
+        range: string;
+        requests: Record<string, unknown>[];
+        result?: undefined;
+    } | {
+        range: string;
+        result: unknown;
+        dryRun?: undefined;
+        requests?: undefined;
+    }>;
+    formula: (id: string, opts: import("./lib/ops.js").FormulaOpts) => Promise<{
+        dryRun: boolean;
+        cell: string;
+        expr: string;
+        result?: undefined;
+    } | {
+        cell: string;
+        expr: string;
+        result: unknown;
+        dryRun?: undefined;
+    }>;
+    fillDown: (id: string, opts: import("./lib/ops.js").FillDownOpts) => Promise<{
+        dryRun: boolean;
+        range: string;
+        expr: string;
+        rows: number;
+        result?: undefined;
+    } | {
+        range: string;
+        expr: string;
+        rows: number;
+        result: unknown;
+        dryRun?: undefined;
+    }>;
+    share: (id: string, opts: import("./lib/ops.js").ShareOpts) => Promise<{
+        dryRun: boolean;
+        email: string;
+        role: string;
+        result?: undefined;
+    } | {
+        email: string;
+        role: string;
+        result: unknown;
+        dryRun?: undefined;
+    }>;
+    unshare: (id: string, email: string, dryRun?: boolean) => Promise<{
+        dryRun: boolean;
+        email: string;
+        permissionId: string;
+        removed?: undefined;
+    } | {
+        email: string;
+        removed: string;
+        dryRun?: undefined;
+        permissionId?: undefined;
+    }>;
+    permissions: (id: string) => Promise<{
+        permissions: {
+            id: string;
+            role: string | undefined;
+            type: string | undefined;
+            email: string | undefined;
+            name: string | undefined;
+        }[];
+    }>;
+    api: (method: string, id: string | undefined, json: unknown) => Promise<{
+        method: string;
+        result: unknown;
+    }>;
+};
+export declare function idOf(positional: string | undefined, g: Globals): string;
+export declare function run(cmdName: string, pretty: boolean, fn: () => Promise<{
+    result: unknown;
+    spreadsheetId?: string;
+    sheet?: string;
+}>): Promise<void>;
+export declare function need(value: string | undefined, flag: string): string;

package/dist/run.js

@@ -0,0 +1,36 @@
+import { getAccessToken } from './auth.js';
+import { GoogleClient } from './http.js';
+import { resolveSpreadsheetId } from './ids.js';
+import { createOps } from './lib/ops.js';
+import { CliError, envelopeErr, envelopeOk, exitCodeFor, stringifyEnvelope } from './output.js';
+export function takeGlobals(cmd) {
+    const opts = cmd.optsWithGlobals();
+    return {
+        pretty: Boolean(opts.pretty),
+        account: opts.account,
+        spreadsheet: opts.spreadsheet,
+        dryRun: Boolean(opts.dryRun),
+        json: Boolean(opts.json),
+    };
+}
+export function opsFor(account) {
+    return createOps(new GoogleClient(() => getAccessToken(account)));
+}
+export function idOf(positional, g) {
+    return resolveSpreadsheetId(positional, g.spreadsheet);
+}
+export async function run(cmdName, pretty, fn) {
+    try {
+        const out = await fn();
+        process.stdout.write(stringifyEnvelope(envelopeOk(cmdName, out.result, out), pretty) + '\n');
+    }
+    catch (err) {
+        process.stdout.write(stringifyEnvelope(envelopeErr(cmdName, err), pretty) + '\n');
+        process.exitCode = exitCodeFor(err);
+    }
+}
+export function need(value, flag) {
+    if (!value)
+        throw new CliError('VALIDATION_ERROR', `${flag} is required`);
+    return value;
+}

package/dist/specs.d.ts

@@ -0,0 +1 @@
+export { COMMANDS, findSpec } from './plugins/sheet/specs.js';

package/dist/specs.js

@@ -0,0 +1 @@
+export { COMMANDS, findSpec } from './plugins/sheet/specs.js';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "clipy-kit",
+  "version": "0.1.0",
+  "description": "Clipy (clp): local intent CLI for humans and agents. Google Sheets plugin first; JSON stdout, CLI login, no rewritten API code.",
+  "type": "module",
+  "bin": {
+    "clp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/lib/index.d.ts",
+      "import": "./dist/lib/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clp": "tsx src/cli.ts",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "cli",
+    "agent-skills",
+    "google-sheets",
+    "clipy",
+    "clp",
+    "clipy-kit"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "google-auth-library": "^9.15.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/skills/clipy/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: clipy
+description: >-
+  Clipy host CLI (binary: clp). Use when installing or diagnosing clipy,
+  listing plugins, or when the user mentions Clipy, clp setup, clp
+  doctor, or adding sheet/jira/linear tools. Never write OAuth or API client
+  code — run clp commands. For Google Sheets details, also read the clipy-sheet skill.
+---
+
+# clp — Clipy
+
+One PATH binary for humans and agents. JSON on stdout for data commands.
+
+## If `clp` is missing
+
+```bash
+npm i -g clipy-kit
+clp setup
+clp doctor --json
+```
+
+Do not edit PATH by hand and do not generate a wrapper script.
+
+## Host commands
+
+```bash
+clp --help --json
+clp doctor --json
+clp setup
+clp plugin list --json
+clp plugin add sheet
+```
+
+`plugin list` includes **planned** names (linear, github, jira, …). Do not call those plugins; they are not shipped.
+
+## Plugins
+
+Delegate to `clp <plugin> …`. Sheets: `clp sheet --help --json`. Never write `googleapis`, MCP payloads, or login code. If `AUTH_REQUIRED`, run `clp sheet auth login`.

package/skills/clipy-sheet/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: clipy-sheet
+description: >-
+  Read, write, format, and share Google Sheets via `clp sheet`. Use when the
+  user mentions Google Sheets, spreadsheets, Drive tabs, or tabular data in a
+  Google spreadsheet. Never write googleapis, OAuth, or Apps Script — run
+  clp sheet commands.
+---
+
+# clp sheet
+
+Intent-level Google Sheets plugin. JSON on stdout. Do not generate Google client or login code.
+
+## Auth (CLI only)
+
+If a command returns `AUTH_REQUIRED`, run login and wait — do not write OAuth.
+
+```bash
+clp sheet auth status
+clp sheet auth login
+clp sheet auth login --credentials ./client_secret.json
+clp sheet auth login --service-account ./sa.json
+clp sheet auth login --token "$GOOGLE_TOKEN"
+clp sheet auth login --adc
+clp sheet auth logout
+```
+
+## Workflow
+
+`clp sheet auth status` → login if needed → read → `--dry-run` → apply. Prefer `upsert` / `update --key-col`. Check `ok`.
+
+```bash
+clp sheet --help --json
+clp sheet format --help --json
+```
+
+`--spreadsheet` accepts a full URL.
+
+## Commands
+
+```bash
+clp sheet find --name "HPP"
+clp sheet info <id-or-url>
+clp sheet tabs list <id>
+clp sheet read <id> --tab "Sheet1" --limit 100
+clp sheet read range <id> --range 'Sheet1!A1:C10'
+clp sheet append <id> --tab "Sheet1" --rows '[{"Name":"A"}]' --dry-run
+clp sheet update <id> --tab "Sheet1" --key-col Name --key A --set '{"Status":"Done"}'
+clp sheet upsert <id> --tab "Sheet1" --key-col Name --rows '[{"Name":"A","Status":"Done"}]'
+clp sheet set <id> --range 'Sheet1!A1:B2' --values '[["A","B"],["1","2"]]'
+clp sheet clear <id> --range 'Sheet1!A2:Z'
+clp sheet batch <id> --ops '[{"op":"append","sheet":"Sheet1","values":{"Name":"B"}}]'
+clp sheet create --title "Recipes" --tabs "Minuman,Makanan"
+clp sheet tab add <id> --title "Snack"
+clp sheet format <id> --range 'Sheet1!A1:Z1' --bold --bg navy --fg white --align center
+clp sheet format header <id> --tab Sheet1
+clp sheet freeze <id> --tab Sheet1 --rows 1
+clp sheet number-format <id> --range 'Sheet1!B:B' --pattern 'Rp#,##0'
+clp sheet formula <id> --cell 'Sheet1!D2' --expr '=B2+C2'
+clp sheet share <id> --email user@example.com --role writer
+clp sheet permissions <id>
+```
+
+## Rules
+
+- Never write `googleapis`, gviz, Apps Script, or token-exchange code.
+- Never host an OAuth callback — `clp sheet auth login` owns the browser flow.
+- Prefer key columns; `read` returns `_row` if you need a row index.
+- `clp sheet api <method> --json @file.json` only when `--help --json` has no intent command.
+
+Success: `{ "ok": true, "cmd": "...", "result": ... }`. Exit 20 = auth.