@viceme-ai/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2026-07-18
+
+### Features
+
+- automate CLI releases (`b1c27a5`)
+- publish the Viceme CLI through npm (`80a45d3`)
+- add skill agent publishing CLI (`00f173c`)
+
+### Fixes
+
+- harden release and API transport (`c45db91`)
+- satisfy release workflow shellcheck (`96e8c4a`)
+- record publication admission confirmation (`ed27923`)

package/README.md

@@ -0,0 +1,70 @@
+# Viceme CLI
+
+`viceme` is the deterministic client used by the bundled Viceme Agent Skill. Source parsing, LLM compilation, BuildRun materialization, and share publication stay server-side.
+
+## Install
+
+Node.js 18.20 or newer is required for the npm launcher.
+
+```bash
+npm install --global @viceme-ai/cli
+viceme install
+```
+
+For a one-shot bootstrap without a prior global install, use
+`npx --yes @viceme-ai/cli@latest install`.
+
+The root `install` command performs the complete bootstrap: it atomically installs the matching Viceme Skill into Codex and/or Claude Code, creates a non-sensitive local config, checks authentication without printing credentials, and returns the device-login command when needed.
+
+The npm package is intentionally a small launcher, not six copies of the Go executable. It downloads the binary for the package's exact version from the corresponding GitHub Release, verifies the published SHA-256 checksum, writes a complete pair into a unique staging directory, and atomically publishes that directory as an immutable cache generation before executing it. Concurrent cold starts may repeat a download, but never share, overwrite, or delete a mutable binary/checksum pair; an interrupted process leaves only ignored staging state. Supported release targets are macOS and Linux on `amd64`/`arm64`, plus Windows on `amd64`/`arm64`.
+
+## Authenticate and publish
+
+The current Core records `--yes` as a versioned publication-admission confirmation and remains an internal, default-off allowlist probe. That admission permits the background compile, but it is not proof that the user reviewed the resulting immutable Release Candidate. Do not expose it as the public product flow: external rollout is blocked until T2 adds exact-candidate preview and confirmation before commit. The commands below exercise the transport and stable-link Core while that gate is implemented.
+
+```bash
+viceme auth login --no-wait --json
+viceme skill inspect https://github.com/acme/poster-skill --json
+viceme skill publish --resolution-id <resolution-id> --yes --json
+viceme job wait <publication-id> --timeout 60s --json
+```
+
+Credentials are stored only in the operating-system keychain. There is no plaintext token fallback.
+
+## Diagnose and update
+
+```bash
+viceme skills doctor --json
+viceme update --check --json
+viceme update --json
+```
+
+Every Skill installation records its CLI version, Skill version, minimum compatible CLI version, full bundle digest, and agent-readable embedded digest. `skills doctor` validates each item independently.
+
+`viceme update` is supported for the npm launcher. It resolves the latest version, globally installs that exact package with lifecycle scripts disabled, and then invokes the same exact package to acquire its verified binary and reinstall its bundled Skill. A standalone development binary is not silently replaced; bootstrap it through npm first. Homebrew and signed standalone update manifests remain future distribution channels.
+
+## Development and quality gates
+
+```bash
+make build
+make test
+make check
+make npm-package-check
+make quality-check
+```
+
+`make npm-package-check` does not require a published GitHub Release. It injects the locally built Go executable through `VICEME_BINARY_PATH`, packs the npm tarball, and runs the real npm launcher through `install` in an isolated temporary home. The override is for development and CI only.
+
+The checked-in quality artifacts are:
+
+- `skills/viceme/references/command-manifest.json`, generated from the Cobra command tree;
+- `quality/example-dry-runs.json`, which executes the documented inspect/publish paths without network access;
+- `quality/release-manifest.json`, which pins CLI/Skill compatibility and both Skill digests.
+
+Set `VICEME_API_BASE_URL` for local integration. Release asset names are fixed as `viceme_<version>_<goos>_<goarch>[.exe]` with a sibling `.sha256`. The workflow checks that exactly all six binary/checksum pairs exist and blocks npm publication until they have been uploaded to a completed GitHub Release.
+
+Releases do not require a maintainer to edit versions, write a changelog, create a tag, or run `npm publish`. A push to `dev` runs `.github/workflows/release-pr.yml`, which selects the next stable semantic version from Conventional Commits, synchronizes npm/Go/Skill metadata and generated digests, updates `CHANGELOG.md`, runs the release quality gates, and creates or updates the `dev` to `main` Release PR. Merge that PR to approve the release; `.github/workflows/release.yml` then tags the exact reviewed head, reconnects the merged `main` commit into `dev`, creates or verifies the immutable GitHub Release, and publishes or verifies the npm package. See [`docs/releasing.md`](docs/releasing.md) for setup, recovery, and versioning details.
+
+npm publishing uses a pinned OIDC-capable npm CLI and provenance. The steady-state authentication path is GitHub Actions trusted publishing (`id-token: write`): configure `@viceme-ai/cli` to trust `ViceMe-AI/cli` and `.github/workflows/release.yml`. If npm requires a credential for the package's first-ever publication, temporarily configure a granular publish token as the `NPM_TOKEN` repository secret; the workflow exposes it only as `NODE_AUTH_TOKEN` to the final publish-or-verify step. Remove the secret after trusted publishing is configured.
+
+Release reruns are fail-closed. If the GitHub Release already exists, the workflow byte-compares every existing asset with the binaries/checksums rebuilt from the tag, uploads only assets missing after an interrupted release, and then verifies the complete 12-asset set. It never overwrites an existing asset. npm publication accepts stable `x.y.z` versions only. If the exact version already exists, its registry integrity must equal the local `npm pack` integrity; an older `latest` tag is safely promoted to that exact version, while rerunning an older release never demotes a newer `latest`. This lets either publication stage be retried without deleting or replacing immutable content.

package/docs/releasing.md

@@ -0,0 +1,63 @@
+# Automated CLI releases
+
+Viceme CLI uses an automated Release PR as the only normal production release
+gate. Maintainers merge feature and fix PRs into `dev`; they do not edit version
+files, create tags, write changelog entries, or run npm commands locally.
+
+## Normal flow
+
+1. A non-bot push to `dev` starts `Prepare Release PR`.
+2. `npm/scripts/prepare-release.mjs` finds the newest reachable stable tag and
+   reads all unreleased non-merge commits.
+3. Conventional Commits select the next version:
+   - a `BREAKING CHANGE` footer or `type!:` selects major;
+   - `feat:` selects minor;
+   - every other releasable change selects patch.
+4. The workflow synchronizes `package.json`, `package-lock.json`, Go build
+   metadata, bundled Skill metadata, command manifest, release digests, and
+   `CHANGELOG.md`.
+5. It runs `make check` and `make npm-package-check`, commits the generated
+   release files to `dev`, and creates or updates one `dev` to `main` PR titled
+   `chore(release): vX.Y.Z`.
+6. A maintainer reviews and merges that PR using the repository's preferred
+   merge method.
+7. `Release CLI and npm launcher` tags the exact reviewed PR head, reconnects
+   the merged `main` commit into `dev` when necessary, reruns the quality gates,
+   builds six platform binaries and six checksums, creates the GitHub Release,
+   and publishes the npm launcher.
+
+## One-time repository setup
+
+GitHub Actions needs `Read and write permissions` and permission to create pull
+requests so the built-in `GITHUB_TOKEN` can update `dev` and maintain the
+Release PR. No maintainer PAT is required by these workflows.
+
+Configure npm trusted publishing for:
+
+- npm package: `@viceme-ai/cli`;
+- GitHub organization/repository: `ViceMe-AI/cli`;
+- workflow file: `.github/workflows/release.yml`.
+
+Trusted publishing is the steady-state path and uses GitHub OIDC plus npm
+provenance. If npm does not allow trusted publishing to create the package on
+its first release, add a repository secret named `NPM_TOKEN` containing a
+granular automation token limited to `@viceme-ai/cli` publication. Remove that
+secret after the package exists and trusted publishing is confirmed.
+
+No release-specific environment variables are required. `GITHUB_TOKEN` is
+provided by Actions. `NPM_TOKEN` is optional and should only be retained when
+the npm account policy requires it.
+
+## Recovery
+
+The original merged Release PR workflow run is safe to rerun from GitHub
+Actions. Existing tags must point to the same reviewed commit. Existing GitHub
+Release assets are compared byte-for-byte and never overwritten. Existing npm
+versions must have the same registry integrity as the locally packed artifact;
+otherwise the workflow fails closed. A rerun of an older version cannot move
+the npm `latest` tag behind a newer release.
+
+There is deliberately no tag-push or manual-dispatch production trigger. A
+production release can only originate from merging the repository-owned `dev`
+Release PR into `main`; recovery reruns that same authorized event and exact
+reviewed SHA.

package/npm/bin/viceme.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+
+import { ensureBinary } from "../lib/installer.mjs";
+
+export async function main(args = process.argv.slice(2), environment = process.env) {
+  const packageDocument = JSON.parse(
+    await readFile(new URL("../../package.json", import.meta.url), "utf8"),
+  );
+  const binary = await ensureBinary({
+    packageVersion: packageDocument.version,
+    environment,
+  });
+  const child = spawnSync(binary, args, {
+    stdio: "inherit",
+    env: {
+      ...environment,
+      VICEME_INSTALL_METHOD:
+        environment.VICEME_INSTALL_METHOD === "npm"
+          ? "npm"
+          : environment.VICEME_BINARY_PATH
+            ? "development"
+            : "npm",
+      VICEME_NPM_PACKAGE_VERSION: packageDocument.version,
+    },
+    windowsHide: false,
+  });
+  if (child.error) {
+    throw child.error;
+  }
+  if (child.signal) {
+    return 128;
+  }
+  return child.status ?? 1;
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  process.stderr.write(`viceme launcher: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/npm/lib/installer.mjs

@@ -0,0 +1,201 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const RELEASE_BASE_URL = "https://github.com/ViceMe-AI/cli/releases/download";
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const GENERATIONS_DIRECTORY = "generations";
+const GENERATION_PREFIX = "generation-";
+const STAGING_PREFIX = ".staging-";
+
+export function releaseTarget(platform = process.platform, architecture = process.arch) {
+  const operatingSystems = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows",
+  };
+  const architectures = {
+    arm64: "arm64",
+    x64: "amd64",
+  };
+  const operatingSystem = operatingSystems[platform];
+  const goArchitecture = architectures[architecture];
+  if (!operatingSystem || !goArchitecture) {
+    throw new Error(`unsupported platform ${platform}/${architecture}`);
+  }
+  return {
+    operatingSystem,
+    architecture: goArchitecture,
+    extension: platform === "win32" ? ".exe" : "",
+  };
+}
+
+export function releaseAssetName(version, platform, architecture) {
+  if (!VERSION_PATTERN.test(version)) {
+    throw new Error(`invalid package version ${version}`);
+  }
+  const target = releaseTarget(platform, architecture);
+  return `viceme_${version}_${target.operatingSystem}_${target.architecture}${target.extension}`;
+}
+
+export async function ensureBinary({
+  packageVersion,
+  environment = process.env,
+  platform = process.platform,
+  architecture = process.arch,
+  fetchImplementation = globalThis.fetch,
+  releaseBaseURL = RELEASE_BASE_URL,
+  cacheDirectory,
+  allowInsecureURL = false,
+}) {
+  if (environment.VICEME_BINARY_PATH) {
+    const overridden = path.resolve(environment.VICEME_BINARY_PATH);
+    await access(overridden, constants.X_OK);
+    return overridden;
+  }
+  if (typeof fetchImplementation !== "function") {
+    throw new Error("Node.js fetch support is required");
+  }
+  const asset = releaseAssetName(packageVersion, platform, architecture);
+  const root = cacheDirectory ?? defaultCacheDirectory(environment, platform);
+  const destinationDirectory = path.join(root, "cli", packageVersion);
+  const generationsDirectory = path.join(destinationDirectory, GENERATIONS_DIRECTORY);
+  const cached = await findValidGeneration(generationsDirectory, asset);
+  if (cached) {
+    return cached;
+  }
+  await mkdir(generationsDirectory, { recursive: true, mode: 0o700 });
+  const versionURL = `${releaseBaseURL}/v${packageVersion}`;
+  const checksumURL = `${versionURL}/${asset}.sha256`;
+  const binaryURL = `${versionURL}/${asset}`;
+  const [checksumDocument, binary] = await Promise.all([
+    download(checksumURL, fetchImplementation, allowInsecureURL),
+    download(binaryURL, fetchImplementation, allowInsecureURL),
+  ]);
+  const expectedChecksum = parseChecksum(checksumDocument.toString("utf8"));
+  const actualChecksum = digest(binary);
+  if (actualChecksum !== expectedChecksum) {
+    throw new Error(`checksum mismatch for ${asset}`);
+  }
+
+  // If another cold start finished while this process downloaded, reuse its
+  // complete immutable generation. Duplicate downloads are harmless; shared
+  // partially-written binary/checksum pairs do not exist.
+  const publishedByContender = await findValidGeneration(generationsDirectory, asset);
+  if (publishedByContender) {
+    return publishedByContender;
+  }
+
+  const generationID = `${expectedChecksum.slice(0, 16)}-${randomUUID()}`;
+  const stagingDirectory = path.join(
+    destinationDirectory,
+    `${STAGING_PREFIX}${process.pid}-${generationID}`,
+  );
+  const generationDirectory = path.join(
+    generationsDirectory,
+    `${GENERATION_PREFIX}${generationID}`,
+  );
+  const stagedBinary = path.join(stagingDirectory, asset);
+  const stagedChecksum = `${stagedBinary}.sha256`;
+  try {
+    await mkdir(stagingDirectory, { mode: 0o700 });
+    await writeFile(stagedBinary, binary, { mode: 0o700 });
+    await chmod(stagedBinary, 0o700);
+    await writeFile(stagedChecksum, `${expectedChecksum}  ${asset}\n`, { mode: 0o600 });
+    if (!(await cachedBinaryIsValid(stagedBinary, stagedChecksum))) {
+      throw new Error(`staged binary verification failed for ${asset}`);
+    }
+
+    // Staging and generations share a parent filesystem. Renaming the complete
+    // unique directory is the only publication step, and its destination is
+    // never replaced or removed by another installer process.
+    await rename(stagingDirectory, generationDirectory);
+  } finally {
+    await rm(stagingDirectory, { recursive: true, force: true });
+  }
+  const installedBinary = path.join(generationDirectory, asset);
+  if (!(await cachedBinaryIsValid(installedBinary, `${installedBinary}.sha256`))) {
+    throw new Error(`published binary verification failed for ${asset}`);
+  }
+  return installedBinary;
+}
+
+async function findValidGeneration(generationsDirectory, asset) {
+  let entries;
+  try {
+    entries = await readdir(generationsDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+  for (const entry of entries
+    .filter((candidate) => candidate.isDirectory() && candidate.name.startsWith(GENERATION_PREFIX))
+    .sort((left, right) => left.name.localeCompare(right.name))) {
+    const binaryPath = path.join(generationsDirectory, entry.name, asset);
+    if (await cachedBinaryIsValid(binaryPath, `${binaryPath}.sha256`)) {
+      return binaryPath;
+    }
+  }
+  return undefined;
+}
+
+function defaultCacheDirectory(environment, platform) {
+  if (environment.VICEME_CACHE_DIR) {
+    return path.resolve(environment.VICEME_CACHE_DIR);
+  }
+  if (environment.XDG_CACHE_HOME) {
+    return path.join(environment.XDG_CACHE_HOME, "viceme");
+  }
+  if (platform === "win32" && environment.LOCALAPPDATA) {
+    return path.join(environment.LOCALAPPDATA, "Viceme", "Cache");
+  }
+  return path.join(os.homedir(), ".cache", "viceme");
+}
+
+async function cachedBinaryIsValid(binaryPath, checksumPath) {
+  try {
+    const [binary, checksumDocument] = await Promise.all([
+      readFile(binaryPath),
+      readFile(checksumPath, "utf8"),
+      access(binaryPath, constants.X_OK),
+    ]);
+    const expected = parseChecksum(checksumDocument);
+    return digest(binary) === expected;
+  } catch {
+    return false;
+  }
+}
+
+async function download(url, fetchImplementation, allowInsecureURL) {
+  const parsed = new URL(url);
+  if (!allowInsecureURL && parsed.protocol !== "https:") {
+    throw new Error(`refusing non-HTTPS release URL ${url}`);
+  }
+  const response = await fetchImplementation(url, {
+    redirect: "follow",
+    headers: { "user-agent": "@viceme-ai/cli npm launcher" },
+  });
+  if (!response.ok) {
+    throw new Error(`download failed (${response.status}) for ${url}`);
+  }
+  if (!allowInsecureURL && response.url && new URL(response.url).protocol !== "https:") {
+    throw new Error(`release download redirected to a non-HTTPS URL`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function parseChecksum(document) {
+  const match = document.trim().match(/^([a-fA-F0-9]{64})(?:\s|$)/);
+  if (!match) {
+    throw new Error("release checksum document is invalid");
+  }
+  return match[1].toLowerCase();
+}
+
+function digest(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@viceme-ai/cli",
+  "version": "0.1.0",
+  "description": "Install and run the Viceme CLI and Viceme Agent Skill",
+  "type": "module",
+  "bin": {
+    "viceme": "npm/bin/viceme.mjs"
+  },
+  "files": [
+    "npm/bin/",
+    "npm/lib/",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/releasing.md"
+  ],
+  "scripts": {
+    "test": "node --test npm/test/*.test.mjs",
+    "pack:check": "npm pack --dry-run",
+    "release:prepare": "node npm/scripts/prepare-release.mjs --fallback-ref origin/main"
+  },
+  "engines": {
+    "node": ">=18.20.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ViceMe-AI/cli.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "license": "Apache-2.0"
+}