@negokaz/excel-cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 negokaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# excel-cli
+
+`excel-cli` is a command-line tool for treating Excel workbooks, sheets, and ranges as structured resources.
+
+## Features
+
+- Read workbook, sheet, or range data as JSON
+- Read formulas and styles in addition to values
+- Write values, formulas, styles, and sheet properties from JSON
+- Export HTML artifacts under `.excel-cli/` for broad inspection and visual layout checks
+
+**🪟Windows only:**
+
+- Live edits through OLE automation when Excel is available
+- Export PNG captures under `.excel-cli/` through OLE automation
+
+## Installation
+
+Requires Node.js 20 or later.
+
+```sh
+npm install -g @negokaz/excel-cli
+```
+
+## Installing the Agent Skill
+
+This repository also includes an agent skill at [`skills/excel-cli/`](./skills/excel-cli/).
+
+You can install the skill with:
+
+```sh
+gh skill install negokaz/excel-cli excel-cli
+```
+
+## Command Summary
+
+```text
+excel-cli read <file> <path> [--value | --formula | --style]
+excel-cli query <file> <path>
+excel-cli write <file> <path> (--value <json> | --formula <json> | --style <json> | --props <json>)
+excel-cli add <file> <path>
+excel-cli remove <file> <path> [--force]
+excel-cli export <file> <path> --format <html|png> [--formula] [--style]
+```
+
+## Paths
+
+Commands address workbook resources through a canonical `<file> <path>` pair.
+
+Supported initial paths:
+
+- `/`
+- `/Sheet1`
+- `/Sheet1/A1`
+- `/Sheet1/A1:C3`
+
+Path rules:
+
+- paths must begin with `/`
+- sheet names use canonical path segments: Unicode characters are preserved, while ASCII characters that require escaping remain percent-encoded
+- range output is canonicalized to uppercase cell references
+- Excel-style references such as `Sheet1!A1:C3` are rejected
+
+## Examples
+
+Enumerate sheets:
+
+```sh
+excel-cli query book.xlsx /
+```
+
+```json
+{
+  "path": "/",
+  "kind": "sheetCollection",
+  "backend": "excelize",
+  "items": [
+    { "path": "/Data", "kind": "sheet", "name": "Data" },
+    { "path": "/Hidden%20Sheet", "kind": "sheet", "name": "Hidden Sheet" }
+  ]
+}
+```
+
+Read workbook, sheet, and range resources:
+
+```sh
+excel-cli read book.xlsx /
+excel-cli read book.xlsx /Data
+excel-cli read book.xlsx /Data/A1:C2 --formula
+excel-cli read book.xlsx /Data/A1:C2 --style
+```
+
+Write values, formulas, styles, and sheet properties:
+
+```sh
+excel-cli write book.xlsx /Data/A2:B2 --value '[["Alice",95]]'
+excel-cli write book.xlsx /Data/C2 --formula '[["=SUM(3,4)"]]'
+excel-cli write book.xlsx /Data/A1:B1 --style '[[{"font":{"bold":true}}, null]]'
+excel-cli write book.xlsx /Hidden%20Sheet --props '{"hidden":false}'
+```
+
+Create and remove worksheets:
+
+```sh
+excel-cli add book.xlsx /Sales
+excel-cli remove book.xlsx /Sales
+excel-cli remove book.xlsx /Sales --force
+```
+
+`remove` is a dry-run by default. It validates that the sheet can be removed and returns JSON with `wouldRemove: true`. The workbook is only changed when `--force` is provided.
+
+Export derived artifacts:
+
+```sh
+excel-cli export book.xlsx /Data --format html --formula --style
+excel-cli export book.xlsx /Data/A1:C10 --format png
+```
+
+HTML and PNG files are created under `.excel-cli/`.
+
+## Notes
+
+- `write --value`, `write --formula`, and `read --value`, `read --formula` are designed to round-trip through the same 2-dimensional JSON shape
+- `write --style` accepts a 2-dimensional array of style objects or `null`
+- `write --props` currently supports only worksheet `hidden`
+- `remove` fails if the target sheet does not exist or if it is the workbook's only worksheet
+
+The design notes in [docs/](docs/index.md) are the primary reference for command contracts and migration intent.
+
+## Supported Platforms
+
+| Platform | Architecture |
+|----------|--------------|
+| Windows  | x64, arm64   |
+| macOS    | x64, arm64   |
+| Linux    | x64, arm64   |
+
+## License
+
+MIT

package/dist/artifacts.json

@@ -0,0 +1 @@
+[{"name":"metadata.json","path":"dist/metadata.json","internal_type":35,"type":"Metadata"},{"name":"excel-cli","path":"dist/excel-cli_darwin_amd64_v1/excel-cli","goos":"darwin","goarch":"amd64","goamd64":"v1","target":"darwin_amd64_v1","internal_type":4,"type":"Binary","extra":{"Binary":"excel-cli","Builder":"go","Ext":"","ID":"excel-cli"}},{"name":"excel-cli","path":"dist/excel-cli_darwin_arm64_v8.0/excel-cli","goos":"darwin","goarch":"arm64","goarm64":"v8.0","target":"darwin_arm64_v8.0","internal_type":4,"type":"Binary","extra":{"Binary":"excel-cli","Builder":"go","Ext":"","ID":"excel-cli"}},{"name":"excel-cli","path":"dist/excel-cli_linux_amd64_v1/excel-cli","goos":"linux","goarch":"amd64","goamd64":"v1","target":"linux_amd64_v1","internal_type":4,"type":"Binary","extra":{"Binary":"excel-cli","Builder":"go","Ext":"","ID":"excel-cli"}},{"name":"excel-cli.exe","path":"dist/excel-cli_windows_arm64_v8.0/excel-cli.exe","goos":"windows","goarch":"arm64","goarm64":"v8.0","target":"windows_arm64_v8.0","internal_type":4,"type":"Binary","extra":{"Binary":"excel-cli","Builder":"go","Ext":".exe","ID":"excel-cli"}},{"name":"excel-cli.exe","path":"dist/excel-cli_windows_amd64_v1/excel-cli.exe","goos":"windows","goarch":"amd64","goamd64":"v1","target":"windows_amd64_v1","internal_type":4,"type":"Binary","extra":{"Binary":"excel-cli","Builder":"go","Ext":".exe","ID":"excel-cli"}},{"name":"excel-cli","path":"dist/excel-cli_linux_arm64_v8.0/excel-cli","goos":"linux","goarch":"arm64","goarm64":"v8.0","target":"linux_arm64_v8.0","internal_type":4,"type":"Binary","extra":{"Binary":"excel-cli","Builder":"go","Ext":"","ID":"excel-cli"}}]

package/dist/config.yaml

@@ -0,0 +1,150 @@
+version: 2
+project_name: excel-cli
+release:
+  disable: "true"
+builds:
+  - id: excel-cli
+    goos:
+      - windows
+      - darwin
+      - linux
+    goarch:
+      - amd64
+      - arm64
+    goamd64:
+      - v1
+    go386:
+      - sse2
+    goarm:
+      - "6"
+    goarm64:
+      - v8.0
+    gomips:
+      - hardfloat
+    goppc64:
+      - power8
+    goriscv64:
+      - rva20u64
+    targets:
+      - windows_amd64_v1
+      - windows_arm64_v8.0
+      - darwin_amd64_v1
+      - darwin_arm64_v8.0
+      - linux_amd64_v1
+      - linux_arm64_v8.0
+    dir: .
+    main: .
+    binary: excel-cli
+    builder: go
+    tool: go
+    command: build
+    ldflags:
+      - -s -w
+    env:
+      - CGO_ENABLED=0
+archives:
+  - id: default
+    builds_info:
+      mode: 493
+    name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ with .Arm }}v{{ . }}{{ end }}{{ with .Mips }}_{{ . }}{{ end }}{{ if not (eq .Amd64 "v1") }}{{ .Amd64 }}{{ end }}'
+    formats:
+      - tar.gz
+    files:
+      - src: license*
+      - src: LICENSE*
+      - src: readme*
+      - src: README*
+      - src: changelog*
+      - src: CHANGELOG*
+srpm:
+  nfpmrpm: {}
+  package_name: excel-cli
+  file_name_template: '{{ .PackageName }}-{{ .Version }}.src.rpm'
+  bins:
+    excel-cli: '%{goipath}'
+snapshot:
+  version_template: '{{ .Version }}-SNAPSHOT-{{ .ShortCommit }}'
+checksum:
+  name_template: '{{ .ProjectName }}_{{ .Version }}_checksums.txt'
+  algorithm: sha256
+docker_digest:
+  name_template: digests.txt
+changelog:
+  format: '{{ .SHA }} {{ .Message }}'
+dist: dist
+env_files:
+  github_token: ~/.config/goreleaser/github_token
+  gitlab_token: ~/.config/goreleaser/gitlab_token
+  gitea_token: ~/.config/goreleaser/gitea_token
+source:
+  name_template: '{{ .ProjectName }}-{{ .Version }}'
+  format: tar.gz
+gomod:
+  gobinary: go
+announce:
+  twitter:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+  mastodon:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+    server: ""
+  reddit:
+    title_template: '{{ .ProjectName }} {{ .Tag }} is out!'
+    url_template: '{{ .ReleaseURL }}'
+  slack:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+    username: GoReleaser
+  discord:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+    author: GoReleaser
+    color: "3888754"
+    icon_url: https://goreleaser.com/static/avatar.png
+  teams:
+    title_template: '{{ .ProjectName }} {{ .Tag }} is out!'
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+    color: '#2D313E'
+    icon_url: https://goreleaser.com/static/avatar.png
+  smtp:
+    subject_template: '{{ .ProjectName }} {{ .Tag }} is out!'
+    body_template: 'You can view details from: {{ .ReleaseURL }}'
+  mattermost:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+    title_template: '{{ .ProjectName }} {{ .Tag }} is out!'
+    color: '#2D313E'
+    username: GoReleaser
+  linkedin:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+  telegram:
+    message_template: '{{ print .ProjectName " " .Tag " is out! Check it out at " .ReleaseURL | mdv2escape }}'
+    parse_mode: MarkdownV2
+  webhook:
+    message_template: '{ "message": "{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}"}'
+    content_type: application/json; charset=utf-8
+    expected_status_codes:
+      - 200
+      - 201
+      - 202
+      - 204
+  opencollective:
+    title_template: '{{ .Tag }}'
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out!<br/>Check it out at <a href="{{ .ReleaseURL }}">{{ .ReleaseURL }}</a>'
+  bluesky:
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+  discourse:
+    title_template: '{{ .ProjectName }} {{ .Tag }} is out!'
+    message_template: '{{ .ProjectName }} {{ .Tag }} is out! Check it out at {{ .ReleaseURL }}'
+    username: system
+git:
+  tag_sort: -version:refname
+mcp:
+  name: ""
+  title: ""
+  auth:
+    type: none
+retry:
+  attempts: 10
+  delay: 10s
+  max_delay: 5m0s
+github_urls:
+  download: https://github.com
+gitlab_urls:
+  download: https://gitlab.com

package/dist/launcher.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const run_launcher_1 = require("./run-launcher");
+(0, run_launcher_1.executeLauncher)(__dirname, process);

package/dist/metadata.json

@@ -0,0 +1 @@
+{"project_name":"excel-cli","tag":"v0.3.0","previous_tag":"v0.2.0","version":"0.3.0-SNAPSHOT-577cff9","commit":"577cff9ff59726dd9b0341b1bb7a5b053aaf1d26","date":"2026-06-07T13:17:03.769006632Z","runtime":{"goos":"linux","goarch":"amd64"}}

package/dist/resolve-binary-path.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBinaryPath = resolveBinaryPath;
+const path = __importStar(require("path"));
+const SUPPORTED_TARGETS = [
+    { platform: 'win32', arch: 'x64', distributionDir: 'excel-cli_windows_amd64_v1', binaryFileName: 'excel-cli.exe' },
+    { platform: 'win32', arch: 'arm64', distributionDir: 'excel-cli_windows_arm64_v8.0', binaryFileName: 'excel-cli.exe' },
+    { platform: 'darwin', arch: 'x64', distributionDir: 'excel-cli_darwin_amd64_v1', binaryFileName: 'excel-cli' },
+    { platform: 'darwin', arch: 'arm64', distributionDir: 'excel-cli_darwin_arm64_v8.0', binaryFileName: 'excel-cli' },
+    { platform: 'linux', arch: 'x64', distributionDir: 'excel-cli_linux_amd64_v1', binaryFileName: 'excel-cli' },
+    { platform: 'linux', arch: 'arm64', distributionDir: 'excel-cli_linux_arm64_v8.0', binaryFileName: 'excel-cli' },
+];
+function getTarget(platform, arch) {
+    const target = SUPPORTED_TARGETS.find((entry) => entry.platform === platform && entry.arch === arch);
+    if (target === undefined) {
+        throw new Error(`Unsupported platform: ${platform}_${arch} (platform=${platform}, arch=${arch})`);
+    }
+    return target;
+}
+function resolveBinaryPath(platform, arch, baseDir, existsSync) {
+    const target = getTarget(platform, arch);
+    const binaryPath = path.resolve(baseDir, target.distributionDir, target.binaryFileName);
+    if (!existsSync(binaryPath)) {
+        throw new Error(`Binary not found: ${binaryPath}`);
+    }
+    return binaryPath;
+}

package/dist/run-launcher.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeLauncher = executeLauncher;
+const childProcess = __importStar(require("child_process"));
+const fs = __importStar(require("fs"));
+const resolve_binary_path_1 = require("./resolve-binary-path");
+function formatErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function runLauncher(baseDir, runtimeProcess, dependencies) {
+    const binaryPath = (0, resolve_binary_path_1.resolveBinaryPath)(runtimeProcess.platform, runtimeProcess.arch, baseDir, dependencies.existsSync);
+    const result = dependencies.spawnSync(binaryPath, runtimeProcess.argv.slice(2), { stdio: 'inherit' });
+    if (result.error !== undefined) {
+        throw result.error;
+    }
+    if (result.signal !== null) {
+        throw new Error(`Binary terminated by signal: ${result.signal}`);
+    }
+    if (typeof result.status !== 'number') {
+        throw new Error(`Binary exited without a status code: ${binaryPath}`);
+    }
+    if (result.status !== 0) {
+        runtimeProcess.exit(result.status);
+    }
+}
+function executeLauncher(baseDir, runtimeProcess) {
+    try {
+        runLauncher(baseDir, runtimeProcess, {
+            existsSync: fs.existsSync,
+            spawnSync: childProcess.spawnSync,
+        });
+    }
+    catch (error) {
+        runtimeProcess.stderr.write(`${formatErrorMessage(error)}\n`);
+        runtimeProcess.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@negokaz/excel-cli",
+  "version": "0.3.0",
+  "description": "CLI tool for Excel operations",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/negokaz/excel-cli.git"
+  },
+  "homepage": "https://github.com/negokaz/excel-cli#readme",
+  "bugs": {
+    "url": "https://github.com/negokaz/excel-cli/issues"
+  },
+  "bin": {
+    "excel-cli": "dist/launcher.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "goreleaser build --snapshot --clean && tsc",
+    "test": "go test ./... && jest --runInBand",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "foam-cli": "^0.43.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/launcher/**/*.test.ts"
+    ]
+  }
+}