@jarel/myskills 0.1.0-alpha.2 → 0.1.0-beta.2

package/README.md

@@ -2,6 +2,8 @@
 
 Command-line client for MySkills.
 
+Supported runtime: Node.js `>=22.13 <23 || >=24 <25`.
+
 Package:
 
 ```text
@@ -49,7 +51,14 @@ myskills config reset api-url
 myskills config list
 myskills submit --path <file-directory-or-zip> [--api-url <url>] [--token <token>]
 myskills review submissions [--api-url <url>] [--token <token>]
-myskills review action <submission-id> --action <approve|publish> [--reason <text>]
+myskills review bundle <submission-id> [--platform <name>] [--output <file>] [--api-url <url>] [--token <token>]
+myskills review action <submission-id> --action <approve|request-changes|reject|publish> [--artifact-sha256 <hash>] [--reason <text>] [--api-url <url>] [--token <token>]
+myskills submissions list [--api-url <url>] [--token <token>]
+myskills submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]
+myskills skills edit <skill-slug> [--title <text>] [--summary <text>] [--visibility <scope>] [--tag <tag>] [--reason <text>] [--api-url <url>] [--token <token>]
+myskills skills archive|restore|delete <skill-slug> [--reason <text>] [--api-url <url>] [--token <token>]
+myskills releases list <skill-slug> [--api-url <url>] [--token <token>]
+myskills releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--reason <text>] [--replacement <version>] [--api-url <url>] [--token <token>]
 myskills teams list|skills [--api-url <url>] [--token <token>]
 myskills teams create <team-name> [--name <team-name>] [--api-url <url>] [--token <token>]
 myskills teams invite <team-id> --email <email> [--api-url <url>] [--token <token>]
@@ -68,9 +77,9 @@ myskills token list
 myskills token revoke <token-id>
 ```
 
-## Public Alpha Install
+## Published And Candidate Channels
 
-The first public alpha package is distributed through npm under the `alpha` tag:
+The currently published package remains available under npm's `alpha` tag:
 
 ```bash
 npm install -g @jarel/myskills@alpha
@@ -84,13 +93,17 @@ Update the CLI with:
 npm install -g @jarel/myskills@alpha
 ```
 
+The `0.1.0-beta.2` source manifest is configured for the `beta` dist-tag, but package publication is a separate maintainer approval step. The release-verification workflow packs and installs the candidate without publishing it.
+
 `validate`, `scan`, and `submit` accept a manifest file, package directory, or local `.zip` package. `login` prompts for the API URL when one is not supplied; the default is the local API at `http://localhost:3001`, and custom hosted URLs can be entered manually. Successful login stores the selected API URL in local CLI config so later commands can omit `--api-url`. API URL resolution is `--api-url`, then `MYSKILLS_API_URL`, then saved config, then `http://localhost:3001`.
 
 `login` supports an email/password session flow and an API-key flow. The email/password flow handles MFA challenges with a TOTP or recovery code prompt and stores only the verified session token. The API-key flow validates the key with `/v1/me` before storing it. Token resolution is `--token`, then `MYSKILLS_TOKEN`, then the stored login token. The default token store uses the platform credential store through `@napi-rs/keyring` and falls back to `tokens.json` with user-only file permissions when keyring storage is unavailable or `MYSKILLS_TOKEN_STORE=file`/`MYSKILLS_TOKEN_FILE` is set. `auth status` validates the current token without printing it. `logout` revokes stored session tokens and clears the local entry; stored API tokens are removed locally and must be revoked with `token revoke`.
 
 `config get api-url`, `config set api-url <url>`, `config reset api-url`, and `config list` manage the saved API URL. `doctor` checks the CLI version, Node version, resolved API URL, `/health`, auth status, token-store backend, install-directory writability, and `/v1/capabilities`. If the CLI is pointed at the web app instead of the API, or a newer command is sent to an older server, command errors include concrete next steps and `--json` returns structured error codes.
 
-`submit` validates and scans locally before sending package directories as normalized text entries or `.zip` packages as base64 archive uploads for server-side extraction. `export` downloads server-authorized bundle content, verifies byte size and SHA-256 against release metadata, and writes normalized package paths under the requested output directory. `install` uses the same verified bundle path, writes into `--dir`, `MYSKILLS_INSTALL_DIR`, or the user data directory, and records local state in `.myskills-app/installed.json`; `update` preserves a rollback snapshot before replacing files, and `rollback` restores the most recent snapshot. `token create` prints the plaintext API token only once and does not overwrite the stored login session. Browser/device login, platform-specific install adapters, and archive creation are still planned.
+`submit` validates and scans locally before sending package directories as normalized text entries or `.zip` packages as base64 archive uploads for server-side extraction. Authors can inspect their submitted versions with `submissions list` and withdraw unreviewed or changes-requested submissions with `submissions withdraw`. Maintainers can fetch the reviewed artifact and approval hash with `review bundle`, then approve, request changes, reject, and publish submitted versions through `review action`.
+
+Published artifacts remain immutable. `skills edit` changes mutable skill metadata only, while `releases deprecate`, `releases unpublish`, `releases revoke`, `releases restore`, and `releases delete` update server-owned lifecycle state for a specific version. Deprecated releases remain visible and installable; unpublished, revoked, archived, and deleted releases are hidden from install/export queries. `export` downloads server-authorized bundle content, verifies byte size and SHA-256 against release metadata, and writes normalized package paths under the requested output directory. `install` uses the same verified bundle path, writes into `--dir`, `MYSKILLS_INSTALL_DIR`, or the user data directory, and records local state in `.myskills-app/installed.json`; `update` preserves a rollback snapshot before replacing files, and `rollback` restores the most recent snapshot. `token create` prints the plaintext API token only once and does not overwrite the stored login session. Browser/device login, platform-specific install adapters, and archive creation are still planned.
 
 Common scopes:
 

package/dist/index.js

@@ -16321,7 +16321,7 @@ function decodePackageText(buffer, relativePath) {
 
 // src/cli.ts
 var DEFAULT_API_URL = "http://localhost:3001";
-var CLI_VERSION = "0.1.0-alpha.2";
+var CLI_VERSION = "0.1.0-beta.2";
 var CLI_VISIBILITY_SCOPES = ["public", "authenticated", "organization", "team", "private", "explicit-users"];
 var LOGIN_AUTH_METHODS = ["password", "api-key"];
 async function runCli(argv, runtime) {
@@ -16363,6 +16363,12 @@ async function runCli(argv, runtime) {
         return await submitCommand(parsed, runtime);
       case "review":
         return await reviewCommand(parsed, runtime);
+      case "submissions":
+        return await submissionsCommand(parsed, runtime);
+      case "skills":
+        return await skillsCommand(parsed, runtime);
+      case "releases":
+        return await releasesCommand(parsed, runtime);
       case "teams":
         return await teamsCommand(parsed, runtime);
       case "sharing":
@@ -16774,16 +16780,21 @@ async function reviewCommand(parsed, runtime) {
   if (subcommand === "action") {
     const submissionId = parsed.args[1];
     if (!submissionId) {
-      throw new CliError("Usage: myskills review action <submission-id> --action <approve|publish>", 2);
+      throw new CliError("Usage: myskills review action <submission-id> --action <approve|request-changes|reject|publish> [--artifact-sha256 <hash>] [--reason <text>] [--api-url <url>] [--token <token>]", 2);
     }
     const action = stringOption(parsed, "action");
-    if (action !== "approve" && action !== "publish") {
-      throw new CliError("--action must be approve or publish.", 2);
+    if (action !== "approve" && action !== "request-changes" && action !== "reject" && action !== "publish") {
+      throw new CliError("--action must be approve, request-changes, reject, or publish.", 2);
     }
     const reason = optionalStringOption(parsed, "reason");
+    const artifactSha256 = optionalStringOption(parsed, "artifact-sha256")?.toLowerCase();
+    if (action === "approve" && !isArtifactSha256(artifactSha256)) {
+      throw new CliError("--artifact-sha256 is required when approving a submission and must be a 64-character SHA-256 hex digest.", 2);
+    }
     const response = await apiPost(`/v1/review/submissions/${encodeURIComponent(submissionId)}/actions`, {
       action,
-      ...reason ? { reason } : {}
+      ...reason ? { reason } : {},
+      ...action === "approve" ? { artifactSha256 } : {}
     }, parsed, runtime, token);
     if (parsed.options.json) {
       runtime.io.stdout(JSON.stringify(response, null, 2));
@@ -16793,7 +16804,172 @@ async function reviewCommand(parsed, runtime) {
     }
     return 0;
   }
-  throw new CliError("Usage: myskills review submissions | review action <submission-id> --action <approve|publish>", 2);
+  if (subcommand === "bundle") {
+    const submissionId = parsed.args[1];
+    if (!submissionId) {
+      throw new CliError("Usage: myskills review bundle <submission-id> [--platform <name>] [--output <file>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const platform = optionalStringOption(parsed, "platform");
+    const query = platform ? `?platform=${encodeURIComponent(platform)}` : "";
+    const response = await apiGetWithHeaders(`/v1/review/submissions/${encodeURIComponent(submissionId)}/bundle${query}`, parsed, runtime, token);
+    const artifactSha256 = response.headers["x-myskills-artifact-sha256"] ?? "";
+    if (!isArtifactSha256(artifactSha256)) {
+      throw new CliError("Review bundle response is missing artifact hash.", 1);
+    }
+    const outputPath = optionalStringOption(parsed, "output");
+    if (outputPath) {
+      await mkdir(path2.dirname(path2.resolve(outputPath)), { recursive: true });
+      await writeFile(path2.resolve(outputPath), response.text, { encoding: "utf8", mode: 384 });
+    }
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify({
+        artifactSha256,
+        ...outputPath ? { output: path2.resolve(outputPath) } : {},
+        payload: parseJsonResponse(`/v1/review/submissions/${submissionId}/bundle`, apiBaseUrl(parsed, runtime), response.text)
+      }, null, 2));
+    } else {
+      runtime.io.stdout(`artifactSha256=${artifactSha256}${outputPath ? `	output=${path2.resolve(outputPath)}` : ""}`);
+    }
+    return 0;
+  }
+  throw new CliError("Usage: myskills review submissions | review bundle <submission-id> | review action <submission-id> --action <approve|request-changes|reject|publish> [--artifact-sha256 <hash>] [--reason <text>]", 2);
+}
+async function submissionsCommand(parsed, runtime) {
+  const token = await requireToken(parsed, runtime);
+  const subcommand = parsed.args[0];
+  if (subcommand === "list" || subcommand === "mine") {
+    const response = await apiGet("/v1/submissions/mine", parsed, runtime, token);
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify(response, null, 2));
+    } else {
+      const submissions = arrayField(response, "submissions");
+      if (submissions.length === 0) {
+        runtime.io.stdout("No submissions.");
+      } else {
+        for (const value of submissions) {
+          const submission = recordField(value, "submission");
+          runtime.io.stdout([
+            requiredRecordString(submission, "id", "Submission response is missing id."),
+            `${requiredRecordString(submission, "slug", "Submission response is missing slug.")}@${requiredRecordString(submission, "version", "Submission response is missing version.")}`,
+            optionalRecordString(submission, "reviewStatus") ?? "-",
+            optionalRecordString(submission, "lifecycleStatus") ?? "-",
+            optionalRecordString(submission, "securityStatus") ?? "-"
+          ].join("	"));
+        }
+      }
+    }
+    return 0;
+  }
+  if (subcommand === "withdraw") {
+    const submissionId = parsed.args[1];
+    if (!submissionId) {
+      throw new CliError("Usage: myskills submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const response = await apiPost(`/v1/submissions/${encodeURIComponent(submissionId)}/actions`, {
+      action: "withdraw",
+      ...reasonPayload(parsed)
+    }, parsed, runtime, token);
+    printNamedRecord(response, "submission", runtime.io, ["id", "slug", "version", "reviewStatus", "lifecycleStatus"]);
+    return 0;
+  }
+  throw new CliError("Usage: myskills submissions list | submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+}
+async function skillsCommand(parsed, runtime) {
+  const token = await requireToken(parsed, runtime);
+  const subcommand = parsed.args[0];
+  const slug = parsed.args[1];
+  if (subcommand === "edit") {
+    if (!slug) {
+      throw new CliError("Usage: myskills skills edit <skill-slug> [--title <text>] [--summary <text>] [--visibility <scope>] [--tag <tag>] [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const payload = {
+      ...reasonPayload(parsed)
+    };
+    const title = optionalStringOption(parsed, "title");
+    const summary = optionalStringOption(parsed, "summary");
+    const visibility = optionalStringOption(parsed, "visibility");
+    const tags = stringListOption(parsed, "tag");
+    if (title !== void 0) {
+      payload.title = title;
+    }
+    if (summary !== void 0) {
+      payload.summary = summary;
+    }
+    if (visibility !== void 0) {
+      if (!CLI_VISIBILITY_SCOPES.includes(visibility)) {
+        throw new CliError(`--visibility must be one of: ${CLI_VISIBILITY_SCOPES.join(", ")}.`, 2);
+      }
+      payload.visibility = visibility;
+    }
+    if (tags.length > 0) {
+      payload.tags = tags;
+    }
+    if (Object.keys(payload).every((key) => key === "reason")) {
+      throw new CliError("At least one metadata option is required.", 2);
+    }
+    const response = await apiPut(`/v1/skills/${encodeURIComponent(parseInstallSlug(slug))}`, payload, parsed, runtime, token);
+    printNamedRecord(response, "skill", runtime.io, ["slug", "title", "lifecycleStatus", "visibility"]);
+    return 0;
+  }
+  if (subcommand === "archive" || subcommand === "restore" || subcommand === "delete") {
+    if (!slug) {
+      throw new CliError("Usage: myskills skills archive|restore|delete <skill-slug> [--reason <text>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const response = await apiPost(`/v1/skills/${encodeURIComponent(parseInstallSlug(slug))}/actions`, {
+      action: subcommand,
+      ...reasonPayload(parsed)
+    }, parsed, runtime, token);
+    printNamedRecord(response, "skill", runtime.io, ["slug", "title", "lifecycleStatus", "visibility"]);
+    return 0;
+  }
+  throw new CliError("Usage: myskills skills edit|archive|restore|delete <skill-slug> [--api-url <url>] [--token <token>]", 2);
+}
+async function releasesCommand(parsed, runtime) {
+  const subcommand = parsed.args[0];
+  if (subcommand === "list") {
+    const slug = parsed.args[1];
+    if (!slug) {
+      throw new CliError("Usage: myskills releases list <skill-slug>", 2);
+    }
+    const token = await tokenOption(parsed, runtime) ?? void 0;
+    const response = await apiGet(`/v1/skills/${encodeURIComponent(parseInstallSlug(slug))}/releases`, parsed, runtime, token);
+    if (parsed.options.json) {
+      runtime.io.stdout(JSON.stringify(response, null, 2));
+    } else {
+      const releases = arrayField(response, "releases");
+      if (releases.length === 0) {
+        runtime.io.stdout("No releases.");
+      } else {
+        for (const value of releases) {
+          const release = recordField(value, "release");
+          runtime.io.stdout([
+            `${requiredRecordString(release, "slug", "Release response is missing slug.")}@${requiredRecordString(release, "version", "Release response is missing version.")}`,
+            optionalRecordString(release, "lifecycleStatus") ?? "-",
+            optionalRecordString(release, "reviewStatus") ?? "-",
+            optionalRecordString(release, "securityStatus") ?? "-",
+            `published=${optionalRecordString(release, "publishedAt") ?? "-"}`
+          ].join("	"));
+        }
+      }
+    }
+    return 0;
+  }
+  if (["deprecate", "unpublish", "revoke", "restore", "delete"].includes(subcommand ?? "")) {
+    const target = parsed.args[1];
+    if (!target) {
+      throw new CliError("Usage: myskills releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--reason <text>] [--replacement <version>] [--api-url <url>] [--token <token>]", 2);
+    }
+    const { slug, version: version2 } = parseReleaseTarget(target);
+    const token = await requireToken(parsed, runtime);
+    const response = await apiPost(`/v1/skills/${encodeURIComponent(slug)}/releases/${encodeURIComponent(version2)}/actions`, {
+      action: subcommand,
+      ...reasonPayload(parsed),
+      ...optionalStringOption(parsed, "replacement") ? { replacement: optionalStringOption(parsed, "replacement") } : {}
+    }, parsed, runtime, token);
+    printNamedRecord(response, "release", runtime.io, ["slug", "version", "lifecycleStatus", "reviewStatus", "securityStatus"]);
+    return 0;
+  }
+  throw new CliError("Usage: myskills releases list <skill-slug> | releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--api-url <url>] [--token <token>]", 2);
 }
 async function teamsCommand(parsed, runtime) {
   const token = await requireToken(parsed, runtime);
@@ -17508,6 +17684,26 @@ function recordField(input, label) {
   }
   return input;
 }
+function printNamedRecord(response, key, io, fields) {
+  const record2 = recordField(response[key], key);
+  io.stdout(fields.map((field) => optionalRecordString(record2, field) ?? "-").join("	"));
+}
+function reasonPayload(parsed) {
+  const reason = optionalStringOption(parsed, "reason");
+  return reason ? { reason } : {};
+}
+function parseReleaseTarget(target) {
+  const separator = target.lastIndexOf("@");
+  if (separator <= 0 || separator === target.length - 1) {
+    throw new CliError("Release target must be <skill-slug>@<version>.", 2);
+  }
+  const slug = parseInstallSlug(target.slice(0, separator));
+  const version2 = target.slice(separator + 1);
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version2)) {
+    throw new CliError("Release version is invalid.", 2);
+  }
+  return { slug, version: version2 };
+}
 function arrayField(record2, key) {
   const value = record2[key];
   return Array.isArray(value) ? value : [];
@@ -17570,6 +17766,21 @@ async function apiGet(pathname, parsed, runtime, token) {
   }
   return await apiJsonRequest(pathname, parsed, runtime, { headers });
 }
+async function apiGetWithHeaders(pathname, parsed, runtime, token) {
+  const headers = {};
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  const response = await apiFetch(pathname, parsed, runtime, { headers });
+  if (!response.ok) {
+    const body = parseJsonResponse(pathname, apiBaseUrl(parsed, runtime), response.text);
+    throw apiErrorFromBody(pathname, apiBaseUrl(parsed, runtime), response.status, body, response.text);
+  }
+  return {
+    headers: response.headers,
+    text: response.text
+  };
+}
 async function apiGetText(pathname, parsed, runtime, token) {
   const headers = {};
   if (token) {
@@ -17639,11 +17850,21 @@ async function apiFetch(pathname, parsed, runtime, init) {
     ].join("\n"), 1, "API_UNREACHABLE");
   }
   return {
+    headers: responseHeaders(response.headers),
     ok: response.ok,
     status: response.status,
     text: await response.text()
   };
 }
+function responseHeaders(input) {
+  if (!input) {
+    return {};
+  }
+  if (input instanceof Headers) {
+    return Object.fromEntries([...input.entries()].map(([key, value]) => [key.toLowerCase(), value]));
+  }
+  return Object.fromEntries(Object.entries(input).map(([key, value]) => [key.toLowerCase(), value]));
+}
 function parseJsonResponse(pathname, baseUrl, text) {
   if (!text) {
     return {};
@@ -18028,6 +18249,9 @@ function optionalStringOption(parsed, key) {
   const value = parsed.options[key];
   return typeof value === "string" && value ? value : void 0;
 }
+function isArtifactSha256(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
 function stringListOption(parsed, key) {
   const value = parsed.options[key];
   if (typeof value === "string") {
@@ -18147,7 +18371,14 @@ function helpText() {
     "  config list",
     "  submit --path <file-directory-or-zip> [--api-url <url>] [--token <token>]",
     "  review submissions [--api-url <url>] [--token <token>]",
-    "  review action <submission-id> --action <approve|publish> [--reason <text>]",
+    "  review bundle <submission-id> [--platform <name>] [--output <file>] [--api-url <url>] [--token <token>]",
+    "  review action <submission-id> --action <approve|request-changes|reject|publish> [--artifact-sha256 <hash>] [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  submissions list [--api-url <url>] [--token <token>]",
+    "  submissions withdraw <submission-id> [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  skills edit <skill-slug> [--title <text>] [--summary <text>] [--visibility <scope>] [--tag <tag>] [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  skills archive|restore|delete <skill-slug> [--reason <text>] [--api-url <url>] [--token <token>]",
+    "  releases list <skill-slug> [--api-url <url>] [--token <token>]",
+    "  releases deprecate|unpublish|revoke|restore|delete <skill-slug>@<version> [--reason <text>] [--replacement <version>] [--api-url <url>] [--token <token>]",
     "  teams list|skills [--api-url <url>] [--token <token>]",
     "  teams create <team-name> [--name <team-name>] [--api-url <url>] [--token <token>]",
     "  teams invite <team-id> --email <email> [--api-url <url>] [--token <token>]",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarel/myskills",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-beta.2",
   "description": "Command-line client for publishing, discovering, installing, updating, and rolling back MySkills packages.",
   "license": "Apache-2.0",
   "private": false,
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13 <23 || >=24 <25"
   },
   "repository": {
     "type": "git",
@@ -33,7 +33,7 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "alpha",
+    "tag": "beta",
     "provenance": true
   },
   "scripts": {
@@ -41,7 +41,7 @@
     "test": "node ../../scripts/run-node-tests.mjs --import tsx --extensions .test.ts"
   },
   "devDependencies": {
-    "@myskills-app/skill-package": "0.1.0-alpha.0",
+    "@myskills-app/skill-package": "0.1.0-beta.2",
     "esbuild": "^0.28.1",
     "tsx": "^4.20.6"
   },