clipy-kit 0.1.0

package/dist/plugins/sheet/specs.js

@@ -0,0 +1,291 @@
+const spreadsheetArg = {
+    name: 'spreadsheet',
+    required: false,
+    description: 'Spreadsheet ID or URL (or --spreadsheet)',
+};
+const tabOpt = { flags: '--tab <name>', description: 'Tab / sheet name' };
+const dry = { flags: '--dry-run', description: 'Preview without applying' };
+const rangeOpt = { flags: '--range <a1>', description: 'A1 range, optionally Sheet!A1:B2' };
+export const COMMANDS = [
+    {
+        name: 'auth',
+        description: 'Login, status, and logout. All login is CLI-triggered — never write OAuth code.',
+        subcommands: [
+            {
+                name: 'login',
+                description: 'Start login from the CLI (browser OAuth, service account, token, or ADC)',
+                options: [
+                    { flags: '--credentials <file>', description: 'OAuth desktop client_secret.json' },
+                    { flags: '--service-account <file>', description: 'Service account JSON key' },
+                    { flags: '--token <token>', description: 'Pre-issued access token' },
+                    { flags: '--token-file <file>', description: 'File containing an access token' },
+                    { flags: '--adc', description: 'Use Application Default Credentials (gcloud)' },
+                    { flags: '--account <name>', description: 'Named credential profile (default: default)' },
+                ],
+            },
+            { name: 'status', description: 'Show whether this machine is logged in', options: [{ flags: '--account <name>', description: 'Named profile' }] },
+            { name: 'logout', description: 'Delete stored credentials for a profile', options: [{ flags: '--account <name>', description: 'Named profile' }] },
+        ],
+    },
+    {
+        name: 'find',
+        description: 'Search Drive for spreadsheets by name',
+        options: [
+            { flags: '--name <query>', description: 'Name substring' },
+            { flags: '--limit <n>', description: 'Max results', type: 'number' },
+        ],
+    },
+    { name: 'info', description: 'Spreadsheet title, URL, and tabs', args: [spreadsheetArg] },
+    {
+        name: 'tabs',
+        description: 'List tabs',
+        subcommands: [{ name: 'list', description: 'List tabs in a spreadsheet', args: [spreadsheetArg] }],
+    },
+    {
+        name: 'read',
+        description: 'Read a tab as objects (headers + _row)',
+        args: [spreadsheetArg],
+        options: [
+            tabOpt,
+            rangeOpt,
+            { flags: '--limit <n>', description: 'Max data rows', type: 'number' },
+            { flags: '--header-row <n>', description: '1-based header row (auto-detect if omitted)', type: 'number' },
+            { flags: '--raw', description: 'Return a 2D array instead of objects' },
+        ],
+        subcommands: [
+            {
+                name: 'range',
+                description: 'Read a raw A1 range as a 2D array',
+                args: [spreadsheetArg],
+                options: [{ flags: '--range <a1>', description: 'A1 range', type: 'string' }],
+            },
+        ],
+    },
+    {
+        name: 'append',
+        description: 'Append object rows (creates a header row on an empty tab)',
+        args: [spreadsheetArg],
+        options: [tabOpt, { flags: '--rows <json>', description: 'JSON object, array of objects, or @file.json' }, dry],
+    },
+    {
+        name: 'update',
+        description: 'Update rows by key column (preferred over row index)',
+        args: [spreadsheetArg],
+        options: [
+            tabOpt,
+            { flags: '--key-col <name>', description: 'Column to match' },
+            { flags: '--key <value>', description: 'Value to match' },
+            { flags: '--set <json>', description: 'JSON object of columns to set, or @file.json' },
+            { flags: '--allow-multi', description: 'Update every matching row' },
+            dry,
+        ],
+    },
+    {
+        name: 'upsert',
+        description: 'Update existing rows by key, append the rest',
+        args: [spreadsheetArg],
+        options: [
+            tabOpt,
+            { flags: '--key-col <name>', description: 'Key column' },
+            { flags: '--rows <json>', description: 'JSON objects or @file.json' },
+            dry,
+        ],
+    },
+    {
+        name: 'set',
+        description: 'Overwrite an A1 range with a 2D JSON array',
+        args: [spreadsheetArg],
+        options: [rangeOpt, { flags: '--values <json>', description: '2D JSON array or @file.json' }, dry],
+    },
+    {
+        name: 'clear',
+        description: 'Clear values in a range (keeps formatting)',
+        args: [spreadsheetArg],
+        options: [rangeOpt, dry],
+    },
+    {
+        name: 'batch',
+        description: 'Run append/updateKey/updateRow/setRange/clear ops',
+        args: [spreadsheetArg],
+        options: [{ flags: '--ops <json>', description: 'JSON array of ops or @file.json' }, dry],
+    },
+    {
+        name: 'create',
+        description: 'Create a spreadsheet',
+        options: [
+            { flags: '--title <title>', description: 'Spreadsheet title' },
+            { flags: '--tabs <names>', description: 'Comma-separated tab names' },
+            dry,
+        ],
+    },
+    {
+        name: 'tab',
+        description: 'Add, rename, delete, or duplicate a tab',
+        subcommands: [
+            {
+                name: 'add',
+                description: 'Add a tab',
+                args: [spreadsheetArg],
+                options: [
+                    { flags: '--title <name>', description: 'New tab title' },
+                    { flags: '--index <n>', description: 'Insert index', type: 'number' },
+                    dry,
+                ],
+            },
+            {
+                name: 'rename',
+                description: 'Rename a tab',
+                args: [spreadsheetArg],
+                options: [tabOpt, { flags: '--title <name>', description: 'New title' }, dry],
+            },
+            {
+                name: 'delete',
+                description: 'Delete a tab',
+                args: [spreadsheetArg],
+                options: [tabOpt, dry],
+            },
+            {
+                name: 'duplicate',
+                description: 'Duplicate a tab',
+                args: [spreadsheetArg],
+                options: [tabOpt, { flags: '--title <name>', description: 'Name for the copy' }, dry],
+            },
+        ],
+    },
+    {
+        name: 'format',
+        description: 'Format a range with intent flags (not RepeatCellRequest JSON)',
+        args: [spreadsheetArg],
+        options: [
+            rangeOpt,
+            tabOpt,
+            { flags: '--bold', description: 'Bold text' },
+            { flags: '--italic', description: 'Italic text' },
+            { flags: '--bg <color>', description: '#rrggbb or a name (navy, white, …)' },
+            { flags: '--fg <color>', description: 'Foreground color' },
+            { flags: '--align <dir>', description: 'left | center | right' },
+            { flags: '--valign <dir>', description: 'top | middle | bottom' },
+            { flags: '--wrap', description: 'Wrap text' },
+            dry,
+        ],
+        subcommands: [
+            {
+                name: 'header',
+                description: 'Bold/contrast header row and freeze it',
+                args: [spreadsheetArg],
+                options: [tabOpt, { flags: '--bg <color>', description: 'Header background' }, { flags: '--fg <color>', description: 'Header text color' }, { flags: '--no-freeze', description: 'Do not freeze row 1' }, dry],
+            },
+        ],
+    },
+    {
+        name: 'freeze',
+        description: 'Freeze rows and/or columns',
+        args: [spreadsheetArg],
+        options: [
+            tabOpt,
+            { flags: '--rows <n>', description: 'Frozen row count (default 1)', type: 'number' },
+            { flags: '--columns <n>', description: 'Frozen column count', type: 'number' },
+            dry,
+        ],
+    },
+    {
+        name: 'number-format',
+        description: 'Apply a number pattern to a range',
+        args: [spreadsheetArg],
+        options: [rangeOpt, tabOpt, { flags: '--pattern <pattern>', description: "e.g. Rp#,##0 or 0.00%" }, dry],
+    },
+    {
+        name: 'formula',
+        description: 'Write a formula into a cell',
+        args: [spreadsheetArg],
+        options: [
+            { flags: '--cell <a1>', description: 'Target cell, e.g. Sheet1!D2' },
+            { flags: '--expr <formula>', description: 'Formula, with or without leading =' },
+            dry,
+        ],
+    },
+    {
+        name: 'fill-down',
+        description: 'Write a formula down a range',
+        args: [spreadsheetArg],
+        options: [rangeOpt, { flags: '--expr <formula>', description: 'Formula, with or without leading =' }, dry],
+    },
+    {
+        name: 'share',
+        description: 'Share with a user',
+        args: [spreadsheetArg],
+        options: [
+            { flags: '--email <email>', description: 'Google account email' },
+            { flags: '--role <role>', description: 'reader or writer' },
+            dry,
+        ],
+    },
+    {
+        name: 'unshare',
+        description: 'Remove a user permission',
+        args: [spreadsheetArg],
+        options: [{ flags: '--email <email>', description: 'Google account email' }, dry],
+    },
+    {
+        name: 'permissions',
+        description: 'List sharing permissions',
+        args: [spreadsheetArg],
+    },
+    {
+        name: 'api',
+        description: 'Escape hatch for a raw Sheets/Drive method. Use only when no intent command exists.',
+        args: [{ name: 'method', required: true, description: 'e.g. batchUpdate, values.get, spreadsheets.create' }],
+        options: [
+            { flags: '--json <json>', description: 'Request body or @file.json' },
+            { flags: '--spreadsheet <id>', description: 'Spreadsheet ID or URL when the method needs one' },
+        ],
+    },
+];
+export function findSpec(path) {
+    let list = COMMANDS;
+    let found;
+    for (const part of path) {
+        found = list?.find((c) => c.name === part);
+        if (!found)
+            return undefined;
+        list = found.subcommands;
+    }
+    return found;
+}
+export function helpJson(path = []) {
+    if (!path.length) {
+        return {
+            name: 'sheet',
+            description: 'Intent-level Google Sheets plugin. Never write googleapis or OAuth code — run clp sheet commands.',
+            globalOptions: [
+                { flags: '--pretty', description: 'Pretty-print JSON' },
+                { flags: '--account <name>', description: 'Credential profile' },
+                { flags: '--spreadsheet <id>', description: 'Default spreadsheet ID or URL' },
+                { flags: '--dry-run', description: 'Preview writes' },
+                { flags: '--help --json', description: 'Machine-readable command schema' },
+            ],
+            commands: COMMANDS.map(summarize),
+        };
+    }
+    const spec = findSpec(path);
+    if (!spec) {
+        return { error: { code: 'UNKNOWN_COMMAND', message: `No command: ${path.join(' ')}`, commands: COMMANDS.map((c) => c.name) } };
+    }
+    return expand(spec);
+}
+function summarize(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        subcommands: spec.subcommands?.map((s) => s.name),
+    };
+}
+function expand(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        args: spec.args ?? [],
+        options: spec.options ?? [],
+        subcommands: spec.subcommands?.map(expand),
+    };
+}

package/dist/plugins/types.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+export type ClipyPlugin = {
+    name: string;
+    description: string;
+    register(cmd: Command): void;
+    helpJson(path: string[]): unknown;
+};

package/dist/plugins/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ranges.d.ts

@@ -0,0 +1,20 @@
+export type GridRange = {
+    sheetId: number;
+    startRowIndex?: number;
+    endRowIndex?: number;
+    startColumnIndex?: number;
+    endColumnIndex?: number;
+};
+export type ParsedA1 = {
+    sheet?: string;
+    startCol: number;
+    startRow: number;
+    endCol?: number;
+    endRow?: number;
+};
+export declare function colLetter(index: number): string;
+export declare function colIndex(letters: string): number;
+export declare function parseA1(range: string): ParsedA1;
+export declare function qualifyRange(range: string, tab?: string): string;
+export declare function toGridRange(parsed: ParsedA1, sheetId: number): GridRange;
+export declare function a1FromParts(sheet: string, startCol: number, startRow: number, endCol?: number, endRow?: number): string;

package/dist/ranges.js

@@ -0,0 +1,77 @@
+import { CliError } from './output.js';
+export function colLetter(index) {
+    let n = index + 1;
+    let s = '';
+    while (n > 0) {
+        const rem = (n - 1) % 26;
+        s = String.fromCharCode(65 + rem) + s;
+        n = Math.floor((n - 1) / 26);
+    }
+    return s;
+}
+export function colIndex(letters) {
+    let n = 0;
+    for (const ch of letters.toUpperCase()) {
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    }
+    return n - 1;
+}
+const A1_CELL = /([A-Za-z]+)?(\d+)?/;
+export function parseA1(range) {
+    const trimmed = range.trim();
+    if (!trimmed)
+        throw new CliError('VALIDATION_ERROR', 'Range is required');
+    let sheet;
+    let a1 = trimmed;
+    const bang = trimmed.lastIndexOf('!');
+    if (bang !== -1) {
+        sheet = trimmed.slice(0, bang).replace(/^'|'$/g, '').replace(/''/g, "'");
+        a1 = trimmed.slice(bang + 1);
+    }
+    const [startRaw, endRaw] = a1.split(':');
+    const start = parseCorner(startRaw);
+    const end = endRaw ? parseCorner(endRaw) : undefined;
+    return {
+        sheet,
+        startCol: start.col ?? 0,
+        startRow: start.row ?? 0,
+        endCol: end?.col !== undefined ? end.col + 1 : start.col !== undefined && !endRaw ? start.col + 1 : end?.col,
+        endRow: end?.row !== undefined ? end.row + 1 : start.row !== undefined && !endRaw ? start.row + 1 : end?.row,
+    };
+}
+function parseCorner(raw) {
+    const m = raw.trim().match(A1_CELL);
+    if (!m)
+        throw new CliError('VALIDATION_ERROR', `Invalid A1 notation: ${raw}`);
+    const col = m[1] ? colIndex(m[1]) : undefined;
+    const row = m[2] ? Number(m[2]) - 1 : undefined;
+    return { col, row };
+}
+export function qualifyRange(range, tab) {
+    if (range.includes('!'))
+        return range;
+    if (!tab)
+        return range;
+    const safe = tab.includes(' ') || /[^A-Za-z0-9_]/.test(tab) ? `'${tab.replace(/'/g, "''")}'` : tab;
+    return `${safe}!${range}`;
+}
+export function toGridRange(parsed, sheetId) {
+    const range = { sheetId };
+    if (parsed.startRow !== undefined)
+        range.startRowIndex = parsed.startRow;
+    if (parsed.endRow !== undefined)
+        range.endRowIndex = parsed.endRow;
+    if (parsed.startCol !== undefined)
+        range.startColumnIndex = parsed.startCol;
+    if (parsed.endCol !== undefined)
+        range.endColumnIndex = parsed.endCol;
+    return range;
+}
+export function a1FromParts(sheet, startCol, startRow, endCol, endRow) {
+    const safe = sheet.includes(' ') || /[^A-Za-z0-9_]/.test(sheet) ? `'${sheet.replace(/'/g, "''")}'` : sheet;
+    const start = `${colLetter(startCol)}${startRow + 1}`;
+    if (endCol === undefined && endRow === undefined)
+        return `${safe}!${start}`;
+    const end = `${colLetter((endCol ?? startCol + 1) - 1)}${(endRow ?? startRow + 1)}`;
+    return `${safe}!${start}:${end}`;
+}