@pasko70/pibo 1.2.0 → 1.3.0

package/dist/vscode/vsix-fetcher.js

@@ -0,0 +1,131 @@
+/**
+ * GitHub Releases interaction for the Pibo VS Code extension.
+ *
+ * `pibo vscode install` defaults to fetching the latest VSIX asset from a
+ * GitHub Release. The fetch path is pure-functional so the install command
+ * can inject a mocked fetch and a mocked spawn in tests.
+ */
+export class VsixFetchError extends Error {
+    cause;
+    constructor(message, options) {
+        super(message);
+        this.name = "VsixFetchError";
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
+const VSIX_ASSET_PATTERN = /\.vsix$/i;
+export function isVsixAsset(asset) {
+    return VSIX_ASSET_PATTERN.test(asset.name);
+}
+export function findVsixAsset(release) {
+    return release.assets.find(isVsixAsset);
+}
+const GITHUB_API_ROOT = "https://api.github.com";
+function buildReleaseUrl(owner, repo, tagName) {
+    const base = `${GITHUB_API_ROOT}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/releases`;
+    if (tagName)
+        return `${base}/tags/${encodeURIComponent(tagName)}`;
+    return `${base}/latest`;
+}
+function parseRelease(payload) {
+    if (typeof payload !== "object" || payload === null) {
+        throw new VsixFetchError("GitHub Releases payload is not an object");
+    }
+    const record = payload;
+    const tagName = record.tag_name;
+    const name = record.name;
+    const publishedAt = record.published_at;
+    const htmlUrl = record.html_url;
+    const rawAssets = record.assets;
+    if (typeof tagName !== "string" || typeof name !== "string" || typeof publishedAt !== "string" || typeof htmlUrl !== "string") {
+        throw new VsixFetchError("GitHub Releases payload is missing required string fields");
+    }
+    if (!Array.isArray(rawAssets)) {
+        throw new VsixFetchError("GitHub Releases payload is missing assets array");
+    }
+    const assets = [];
+    for (const raw of rawAssets) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const r = raw;
+        if (typeof r.name === "string" &&
+            typeof r.browser_download_url === "string" &&
+            typeof r.size === "number" &&
+            typeof r.content_type === "string") {
+            assets.push({
+                name: r.name,
+                browserDownloadUrl: r.browser_download_url,
+                size: r.size,
+                contentType: r.content_type,
+            });
+        }
+    }
+    return { tagName, name, publishedAt, htmlUrl, assets };
+}
+export async function fetchRelease(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const url = buildReleaseUrl(options.owner, options.repo, options.tagName);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            headers: { accept: "application/vnd.github+json", "user-agent": "pibo-cli" },
+        });
+    }
+    catch (error) {
+        throw new VsixFetchError(`Failed to call GitHub Releases API at ${url}`, { cause: error });
+    }
+    if (response.status === 404) {
+        throw new VsixFetchError(options.tagName
+            ? `GitHub release ${options.owner}/${options.repo}@${options.tagName} not found`
+            : `GitHub repository ${options.owner}/${options.repo} has no published releases`);
+    }
+    if (!response.ok) {
+        throw new VsixFetchError(`GitHub Releases API returned HTTP ${response.status}`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch (error) {
+        throw new VsixFetchError("GitHub Releases response was not valid JSON", { cause: error });
+    }
+    return parseRelease(payload);
+}
+export async function downloadVsixAsset(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const maxBytes = options.maxBytes ?? 64 * 1024 * 1024; // 64 MiB
+    let response;
+    try {
+        response = await fetchImpl(options.url, { headers: { "user-agent": "pibo-cli" } });
+    }
+    catch (error) {
+        throw new VsixFetchError(`Failed to download VSIX from ${options.url}`, { cause: error });
+    }
+    if (!response.ok) {
+        throw new VsixFetchError(`VSIX download returned HTTP ${response.status}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    if (arrayBuffer.byteLength > maxBytes) {
+        throw new VsixFetchError(`VSIX download is ${arrayBuffer.byteLength} bytes, exceeding limit of ${maxBytes} bytes`);
+    }
+    return Buffer.from(arrayBuffer);
+}
+export async function fetchLatestVsix(options) {
+    const release = await fetchRelease({
+        owner: options.owner,
+        repo: options.repo,
+        tagName: options.tagName,
+        fetchImpl: options.fetchImpl,
+    });
+    const asset = findVsixAsset(release);
+    if (!asset) {
+        throw new VsixFetchError(`Release ${release.tagName} has no .vsix asset`);
+    }
+    const bytes = await downloadVsixAsset({
+        url: asset.browserDownloadUrl,
+        maxBytes: options.maxBytes,
+        fetchImpl: options.fetchImpl,
+    });
+    return { tagName: release.tagName, asset, bytes };
+}

package/docs/ops/vscode-extension-release.md

@@ -0,0 +1,138 @@
+# Pibo VS Code Extension Release Runbook
+
+The Pibo VS Code extension is shipped as a `.vsix` artifact. This runbook describes the end-to-end release process and the split of responsibilities between the maintainer and the `pibo` release script.
+
+## Distribution channels
+
+The extension is published through two channels that are intentionally separate:
+
+| Channel | Owner | Cadence | What it carries |
+|---|---|---|---|
+| npm `@pasko70/pibo` | automated via `npm publish` (or the release script's `--publish-npm` flag) | every `main` commit that includes a version bump | the `pibo` CLI, the gateway, the WebView bundle at `dist/apps/chat-vscode-web/` |
+| VS Code Marketplace `pibo.pibo-vscode` | **maintainer uploads the VSIX manually** via <https://marketplace.visualstudio.com/manage> | every release that needs the extension UI updated | the `.vsix` produced by `npm run vscode:package` |
+
+The npm package and the Marketplace extension are versioned together. The release script bumps both `package.json` (npm) and `src/apps/chat-vscode/package.json` (extension) in one go so the published artifacts stay in lockstep.
+
+`pibo vscode install` (new since the distribution rework) downloads the VSIX from the GitHub Release for the configured repo (`Pascapone/pibo` by default). When the maintainer also uploads the same VSIX to the Marketplace, both channels serve identical bytes.
+
+## Versioning
+
+- The root `package.json#version` is the npm version. It follows [SemVer](https://semver.org/).
+- The extension's `src/apps/chat-vscode/package.json#version` is the Marketplace version. It is kept equal to the npm version (the release script enforces this).
+- A SemVer **minor** bump (e.g., `1.2.0` → `1.3.0`) is appropriate when the change is additive and backward-compatible. The distribution rework itself is a minor bump: existing `pibo` users are unaffected, and the new `pibo vscode install` command is opt-in.
+- A SemVer **major** bump is reserved for breaking changes to either the public CLI surface or the WebView host↔Web postMessage contract.
+
+## Release steps
+
+The release script does the heavy lifting. The maintainer's job is to review, commit, and push.
+
+### 1. Pick the version
+
+Decide on the next version. For the distribution rework that introduces `pibo vscode install`, the right bump is `1.2.0` → `1.3.0` (new CLI command, new marketplace-ready extension, no breaking changes).
+
+### 2. Bump + build + package (local)
+
+From the repo root:
+
+```bash
+node scripts/release.mjs --version 1.3.0
+```
+
+The script:
+
+1. Reads the current version from both `package.json` files.
+2. Writes the new version to both files.
+3. Runs `npm run build` (which includes the WebView build).
+4. Runs `npm run vscode:package` to produce `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix` and a stable `latest.vsix` copy.
+5. Prints the VSIX path and size.
+
+The script does **not** push to git or create a tag. The maintainer reviews the diff and commits it.
+
+### 3. Commit and tag
+
+```bash
+git add package.json src/apps/chat-vscode/package.json
+git commit -m "chore(release): bump @pasko70/pibo and pibo.pibo-vscode to 1.3.0"
+git tag -a v1.3.0 -m "@pasko70/pibo 1.3.0"
+git push origin main
+git push origin v1.3.0
+```
+
+### 4. Create a GitHub Release with the VSIX attached
+
+```bash
+gh release create v1.3.0 \
+  dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix \
+  --title "pibo 1.3.0" \
+  --notes "..."
+```
+
+This makes the VSIX downloadable from a stable URL (`https://github.com/Pascapone/pibo/releases/download/v1.3.0/pibo-vscode-1.3.0.vsix`). The `pibo vscode install` command uses the GitHub Releases API to discover this URL automatically.
+
+The release script can also do this in one step:
+
+```bash
+node scripts/release.mjs --version 1.3.0 --create-release
+```
+
+…if the tag has already been pushed.
+
+### 5. Publish the npm package
+
+```bash
+npm publish
+```
+
+Or, in one go with the release script:
+
+```bash
+node scripts/release.mjs --version 1.3.0 --publish-npm --create-release
+```
+
+The publish step uploads the `pibo` CLI, the gateway plugins, and the WebView bundle. The Marketplace upload is intentionally **not** automated — see step 6.
+
+### 6. Upload the VSIX to the VS Code Marketplace (manual)
+
+The Marketplace does not currently accept a Personal Access Token from this account (Azure-side provisioning issue). The release is therefore finished by uploading the VSIX through the Marketplace web UI:
+
+1. Open <https://marketplace.visualstudio.com/manage>.
+2. Pick the publisher `pibo` (created during the first marketplace publish).
+3. Click **Upload new extension** and select `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix`.
+4. The Marketplace validates the manifest and publishes the extension. The publisher ID is `pibo.pibo-vscode`.
+
+After the upload, `code --install-extension pibo.pibo-vscode` works for end users.
+
+### 7. Verify
+
+```bash
+pibo vscode install --vsix dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix
+pibo vscode status
+```
+
+Confirm that `status` reports `pibo.pibo-vscode@1.3.0` installed via the expected `code` binary, and that the WebView loads the gateway at `http://127.0.0.1:4788/apps/chat-vscode/`.
+
+## Rollback
+
+If a release is broken:
+
+- **npm**: `npm unpublish @pasko70/pibo@1.3.0` works only within 72 hours of publish. After that, publish `1.3.1` with a fix.
+- **VSIX via `pibo vscode install`**: delete the GitHub Release and re-create it with a fixed VSIX. Users who have already installed the extension will not auto-update until they run `pibo vscode install` again.
+- **Marketplace**: the Marketplace UI supports un-publishing or un-listing. For a fast fix, upload a corrected `.vsix` with the same version (the Marketplace accepts a re-upload before processing the original).
+
+## What ships in the `pibo` npm package
+
+The `files` whitelist in `package.json` controls what is published:
+
+- `dist/` — the compiled server, the gateway plugins, the WebView bundles (chat-ui, context-files-ui, chat-vscode-web).
+- `context/` — the bundled agent skills.
+- `skills/builtin/**` — built-in user skills.
+- `docs/ops/**` — operator runbooks.
+- `README.md` and `src/mcp/LICENSE.mcp-cli`.
+
+The `.vsix` is **not** in the npm package. It lives on the GitHub Release and (after the maintainer uploads it) on the VS Code Marketplace.
+
+## Why the WebView bundle is in the npm package
+
+The extension's WebView loads from `http://<gateway>/apps/chat-vscode/`, not from the `.vsix`. The gateway serves the bundle out of `dist/apps/chat-vscode-web/`. If the bundle were not in the npm package, the gateway would return 404 for the WebView and the extension would be unusable.
+
+Including the bundle in npm costs about 1 MB of disk per `pibo` install and zero runtime cost for users who never open the extension. Users who only use the `pibo` CLI never load the bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pasko70/pibo",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Minimal TypeScript wrapper around Pi Coding Agent.",
   "files": [
@@ -35,8 +35,9 @@
     "vscode:typecheck": "tsc -p src/apps/chat-vscode/extension/tsconfig.json --noEmit && tsc -p src/apps/chat-vscode/extension/webview/tsconfig.json --noEmit",
     "vscode:webview:build": "vite build --config src/apps/chat-vscode/extension/webview/vite.config.ts",
     "vscode:extension:build": "esbuild src/apps/chat-vscode/extension/src/extension.ts --bundle --platform=node --target=node24 --format=cjs --outfile=src/apps/chat-vscode/dist/extension/extension.cjs --external:vscode --sourcemap=inline",
-    "vscode:package": "vsce package --no-dependencies",
-    "build": "tsc -p tsconfig.json && npm run web-ui:build && node scripts/ensure-bin-executable.mjs",
+    "vscode:package": "node scripts/vscode-package.mjs",
+    "release": "node scripts/release.mjs",
+    "build": "tsc -p tsconfig.json && npm run web-ui:build && npm run vscode:webview:build && node scripts/ensure-bin-executable.mjs",
     "start": "node dist/bin/pibo.js",
     "test": "npm run build && node --test test/*.test.mjs test/chat-vscode/*.test.mjs",
     "check:product-vocab": "node scripts/legacy-product-vocabulary-gate.mjs",
@@ -85,4 +86,4 @@
     "vite": "^8.0.10",
     "vite-tsconfig-paths": "^5.1.4"
   }
-}
+}