@secureci/cli 0.8.0 → 0.10.0

package/README.md

@@ -36,22 +36,62 @@ far fewer false positives than plain pattern-matching tools.
 
 ## Install
 
+There are two ways to install it: from npm (needs Node.js 20+), or as a
+[standalone binary](#standalone-binary-no-nodejs-needed) for Linux, macOS or
+Windows that needs no Node.js.
+
 ```bash
 npm install -g @secureci/cli
 # or run without installing:
 npx @secureci/cli --help
 ```
 
-Node.js 20+ is required. To build from source instead:
-`npm install && npm run build`.
+To build from source instead: `npm install && npm run build`.
 
 ### Standalone binary (no Node.js needed)
 
-Each [release](https://github.com/secure-ci/cli/releases) has a single-file
-binary for Linux (x64, arm64), macOS (Intel, Apple silicon) and Windows (x64),
-a `SHA256SUMS` file, and a signed build-provenance attestation. Pick the asset
-for your platform: `secureci-linux-x64`, `secureci-linux-arm64`,
-`secureci-darwin-x64`, `secureci-darwin-arm64` or `secureci-win-x64.exe`.
+On macOS or Linux, the install script picks the binary for your platform,
+checks it against the release's `SHA256SUMS` (a mismatch aborts), verifies its
+build provenance when the [GitHub CLI](https://cli.github.com) is signed in, and
+installs it to `~/.local/bin` without `sudo`:
+
+```bash
+curl -fsSL https://secure-ci.dev/install.sh | sh
+```
+
+To read the script before running it ([source](install.sh)):
+
+```bash
+curl -fsSL https://secure-ci.dev/install.sh -o install.sh
+less install.sh
+sh install.sh
+```
+
+Set `SECURECI_VERSION=0.10.0` to install a specific release,
+`SECURECI_INSTALL_DIR` to install somewhere else, and
+`SECURECI_REQUIRE_ATTESTATION=1` to fail unless `gh` verifies build provenance
+(e.g. `curl -fsSL https://secure-ci.dev/install.sh | SECURECI_VERSION=0.10.0 sh`).
+`secure-ci.dev/install.sh` redirects to [`install.sh`](install.sh) on this
+repository's `main` branch.
+
+Or download a binary yourself. Every [release](https://github.com/secure-ci/cli/releases/latest) has a
+single-file binary for each platform below. The links always point to the
+latest release:
+
+| Platform              | Download                                                                                                   |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Linux x64             | [`secureci-linux-x64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-linux-x64)       |
+| Linux arm64           | [`secureci-linux-arm64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-linux-arm64)   |
+| macOS (Apple silicon) | [`secureci-darwin-arm64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-darwin-arm64) |
+| macOS (Intel)         | [`secureci-darwin-x64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-darwin-x64)     |
+| Windows x64           | [`secureci-win-x64.exe`](https://github.com/secure-ci/cli/releases/latest/download/secureci-win-x64.exe)   |
+| Checksums             | [`SHA256SUMS`](https://github.com/secure-ci/cli/releases/latest/download/SHA256SUMS)                       |
+
+Before you run a binary, check it against `SHA256SUMS`. Each binary also has a
+signed build-provenance attestation, which `gh attestation verify` checks. The
+commands below download, verify and install it in one go. To install a
+specific version, take its assets from that version's
+[release page](https://github.com/secure-ci/cli/releases).
 
 ```bash
 # macOS / Linux (here: Linux x64)
@@ -107,6 +147,17 @@ secureci inventory --check    # fail on drift (use in CI)
 secureci pin
 ```
 
+### Agent skill
+
+[`skills/secureci`](skills/secureci/SKILL.md) walks a coding agent (Claude Code,
+Codex, Cursor, …) through setting SecureCI up in a repo: pin actions, commit
+`secureci.lock`, and add the `secure-ci/cli` action as a step in an existing job
+(replacing `actionlint` if present).
+
+```bash
+npx skills add secure-ci/cli --skill secureci
+```
+
 ## Where it shines
 
 - **Fast feedback loop** — iterate on a workflow in seconds instead of

package/dist/cli.js

@@ -278,8 +278,10 @@ initCommand
     .option('--no-upload', 'Do not upload SARIF to code scanning (keeps contents: read only)')
     .option('-o, --output <path>', 'Where to write the workflow', '.github/workflows/secureci.yml')
     .option('-f, --force', 'Overwrite the output file if it already exists')
-    .action((options) => {
-    runInit(options);
+    .option('--no-pin', 'Keep tag refs (e.g. actions/checkout@v4) instead of pinning them to commit SHAs')
+    .option('--offline', 'Pin only refs already in the action cache; others keep their tag')
+    .action(async (options) => {
+    await runInit(options);
 });
 function defaultWorkflowFiles() {
     const dir = path.join(process.cwd(), '.github', 'workflows');
@@ -455,7 +457,6 @@ async function runInventory(files, options) {
     }
     // --dry-run: print the resolved inventory as JSON, touching nothing.
     if (options.dryRun) {
-        // eslint-disable-next-line no-console
         console.log(JSON.stringify({
             actions,
             advisories: advisoryReport.findings,
@@ -788,7 +789,6 @@ async function validateFiles(files, contractFile, recurse, format, offline) {
             say(() => logger_1.logger.info(line.text));
     }
     if (quiet) {
-        // eslint-disable-next-line no-console
         console.log((0, report_1.formatReport)(entries, format, { contract }));
         if (!allValid)
             process.exit(1);
@@ -810,22 +810,36 @@ async function validateFiles(files, contractFile, recurse, format, offline) {
     if (!allValid)
         process.exit(1);
 }
-function runInit(options) {
+async function runInit(options) {
     const output = path.resolve(process.cwd(), options.output);
     if (fs.existsSync(output) && !options.force) {
         logger_1.logger.error(`${options.output} already exists; pass --force to overwrite it.`);
         process.exit(1);
     }
-    const content = (0, init_1.renderInitWorkflow)({
+    let unpinned = [];
+    let content = (0, init_1.renderInitWorkflow)({
         version: (0, version_1.readVersion)(),
         contract: options.contract,
         upload: options.upload
     });
+    // Pin action tags to commit SHAs (`owner/repo@<sha> # v4`), as
+    // `secureci pin` would. A ref that can't be resolved keeps its tag.
+    if (options.pin) {
+        const result = await (0, pin_1.pinContent)(content, (uses) => options.offline
+            ? Promise.resolve((0, action_fetcher_1.cachedActionSha)(uses))
+            : (0, action_fetcher_1.resolveActionSha)(uses));
+        content = result.content;
+        unpinned = result.unresolved;
+    }
     fs.mkdirSync(path.dirname(output), { recursive: true });
     fs.writeFileSync(output, content);
     logger_1.logger.success(`Wrote ${options.output}`);
+    for (const problem of unpinned) {
+        logger_1.logger.warn(`${problem.uses} ${problem.reason}; left on its tag. Run \`secureci pin ${options.output}\` to pin it later.`);
+    }
     if (options.upload) {
-        logger_1.logger.info('The workflow uploads SARIF to code scanning (needs security-events: write).');
+        logger_1.logger.info('The workflow uploads SARIF to code scanning (needs actions: read and security-events: write).');
+        logger_1.logger.info('Code scanning must be enabled for the repository (Settings > Code security) for the SARIF upload to work; otherwise regenerate with --no-upload.');
     }
     logger_1.logger.info('Commit it and open a pull request to see SecureCI run.');
 }

package/dist/init.js

@@ -8,7 +8,8 @@ exports.renderInitWorkflow = renderInitWorkflow;
  *
  * The output is deterministic for a given set of options, so it can be
  * regenerated and diffed. With uploads on (the default) the job asks for
- * `security-events: write` and lets the action upload SARIF; with uploads off
+ * `actions: read` and `security-events: write` and lets the action upload
+ * SARIF; with uploads off
  * it keeps `contents: read` only and passes `upload-sarif: false`.
  */
 function renderInitWorkflow(options) {
@@ -31,8 +32,11 @@ function renderInitWorkflow(options) {
     ];
     // Write scopes belong on the job, not the workflow. Job-level permissions
     // replace the top-level ones, so contents: read is repeated for checkout.
+    // The SARIF upload (github/codeql-action/upload-sarif) needs actions: read
+    // to read the workflow run (required on private repositories) and
+    // security-events: write to upload the results.
     if (upload) {
-        lines.push('    permissions:', '      contents: read', '      security-events: write');
+        lines.push('    # The SARIF upload needs code scanning enabled for this repository', '    # (Settings > Code security; on private repositories this needs', '    # GitHub Code Security / Advanced Security). Without it the upload', '    # step fails: enable it, or give the secure-ci/cli step', '    # `with: upload-sarif: false` (and drop the two scopes below).', '    permissions:', '      contents: read', '      actions: read # upload-sarif reads the workflow run', '      security-events: write # upload SARIF to code scanning');
     }
     lines.push('    steps:', '      - uses: actions/checkout@v4', `      - uses: secure-ci/cli@v${options.version}`);
     const withLines = [];

package/dist/parser/pipeline-contract-parser.js

@@ -66,7 +66,7 @@ function parsePipelineContract(filePath) {
         parsed = YAML.parse(content);
     }
     catch (error) {
-        throw new Error(`Failed to parse contract file: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        throw new Error(`Failed to parse contract file: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
     }
     if (parsed === null || parsed === undefined) {
         return {};

package/dist/parser/workflow-parser.js

@@ -62,7 +62,9 @@ function parseWorkflow(filePath) {
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new Error(`Failed to parse workflow: ${error.message}`);
+            throw new Error(`Failed to parse workflow: ${error.message}`, {
+                cause: error
+            });
         }
         throw error;
     }
@@ -94,7 +96,9 @@ function parseAction(filePath) {
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new Error(`Failed to parse action: ${error.message}`);
+            throw new Error(`Failed to parse action: ${error.message}`, {
+                cause: error
+            });
         }
         throw error;
     }

package/dist/runner/builtin-actions.js

@@ -452,7 +452,7 @@ function findCache(scope, version, key, restoreKeys) {
     if (fs.existsSync(path.join(exact, 'meta.json'))) {
         return { dir: exact, key, created: 0 };
     }
-    let entries = [];
+    let entries;
     try {
         entries = fs
             .readdirSync(scope)

package/dist/runner/github-context.js

@@ -225,7 +225,7 @@ function loadEvent(options, inputs, on) {
         payload = JSON.parse(fs.readFileSync(options.eventPath, 'utf-8'));
     }
     catch (error) {
-        throw new Error(`Invalid event payload ${options.eventPath}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Invalid event payload ${options.eventPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
     if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
         throw new Error(`Invalid event payload ${options.eventPath}: expected a JSON object`);

package/dist/runner/node-action.js

@@ -280,7 +280,7 @@ function runPreIf(action, step, ctx) {
         return (0, expression_1.evaluateCondition)(action.runs['pre-if'] ?? 'always()', ctx);
     }
     catch (error) {
-        throw new Error((0, expression_1.ifEvaluationError)(`step 'Pre ${step.name || step.uses}'`, error));
+        throw new Error((0, expression_1.ifEvaluationError)(`step 'Pre ${step.name || step.uses}'`, error), { cause: error });
     }
 }
 //# sourceMappingURL=node-action.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secureci/cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "SecureCI: validate, check against pipeline standards, and run GitHub Actions workflows locally",
   "main": "dist/index.js",
   "bin": {
@@ -19,7 +19,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "dev": "tsc --watch",
-    "lint": "eslint src --ext .ts",
+    "lint": "eslint src",
     "format": "prettier --write .",
     "prepare": "npm run build"
   },
@@ -63,18 +63,20 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jabraf/dev": "^0.1.4",
+    "@eslint/js": "^10.0.1",
     "@jabraf/prettier": "^3.0.1",
     "@types/node": "^20.10.6",
-    "@typescript-eslint/eslint-plugin": "^8.71.1",
-    "@typescript-eslint/parser": "^8.71.1",
     "@vitest/coverage-v8": "^4.1.12",
-    "eslint": "^8.56.0",
+    "eslint": "^10.14.0",
     "postject": "1.0.0-alpha.6",
     "typescript": "^5.3.3",
+    "typescript-eslint": "^8.72.1",
     "vitest": "^4.1.12"
   },
   "volta": {
     "node": "24.0.0"
+  },
+  "overrides": {
+    "minimatch": "^11.0.4"
   }
 }