actionspack 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2026-PRESENT Kevin Deng (https://github.com/sxzz)
+
+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,166 @@
+# actionspack
+
+[![Open on npmx][npmx-version-src]][npmx-href]
+[![npm downloads][npmx-downloads-src]][npmx-href]
+[![Unit Test][unit-test-src]][unit-test-href]
+
+`actionspack` is a lockfile-first GitHub Actions workflow packer. It lets you
+author workflows in `.github/workflows/src/`, lock every remote workflow/action
+dependency in `.github/workflow.lock.yml`, and generate pinned workflows in
+`.github/workflows/`.
+
+It currently supports inlining composite actions and safely transformable
+reusable workflows. JavaScript and Docker actions are pinned as external
+dependencies instead of being bundled.
+
+## Install
+
+```bash
+npm i actionspack
+```
+
+## Usage
+
+Put authored workflows under `.github/workflows/src/`:
+
+```yaml
+# .github/workflows/src/ci.yml
+name: CI
+
+on:
+  push:
+
+jobs:
+  test:
+    uses: owner/repo/.github/workflows/test.yml@main
+```
+
+Then run:
+
+```bash
+npx actionspack
+```
+
+`actionspack` defaults to `actionspack pack`. It writes:
+
+- `.github/workflow.lock.yml`
+- `.github/workflows/ci.yml`
+
+Generated workflows are safe to commit. Existing lockfile SHAs are reused until
+you explicitly run `actionspack update`.
+
+## Commands
+
+```bash
+actionspack pack
+```
+
+Scan source workflows, resolve missing dependencies, update the lockfile, and
+write generated workflows.
+
+```bash
+actionspack scan
+```
+
+Update the lockfile graph shape only. This adds newly discovered dependencies
+and removes unreachable ones without refreshing existing SHAs.
+
+```bash
+actionspack update [package]
+```
+
+Refresh all locked dependencies, or only the selected package. By default this
+also packs workflows. Use `--lockfile-only` to update only
+`.github/workflow.lock.yml`.
+
+```bash
+actionspack verify
+```
+
+Check that generated workflows are current and contain no unsupported unpinned
+remote references.
+
+```bash
+actionspack tree
+actionspack why <package>
+actionspack diff
+actionspack diff --json
+```
+
+Inspect the lockfile dependency tree, explain why a package is present, or
+compare the current lockfile with `HEAD`.
+
+## Configuration
+
+`actionspack.yml` is optional. Without it, `actionspack` discovers
+`.github/workflows/src/*.yml` and `.github/workflows/src/*.yaml`, then writes
+matching generated workflows to `.github/workflows/*.yml`.
+
+Use explicit entries when you need custom paths:
+
+```yaml
+$schema: ./actionspack.schema.json
+
+entries:
+  - source: .github/workflows/src/ci.yml
+    output: .github/workflows/ci.yml
+```
+
+Use `external` to pin a workflow or action without bundling it:
+
+```yaml
+external:
+  - actions/checkout
+  - owner/repo/path
+```
+
+The same configuration can be supplied through CLI flags:
+
+```bash
+actionspack pack \
+  --entry .github/workflows/src/ci.yml:.github/workflows/ci.yml \
+  --external actions/checkout
+```
+
+## Packing Rules
+
+Composite actions are recursively inlined when `runs.using` is `composite`.
+Inputs are substituted from caller `with` values or action defaults. Missing
+required inputs fail closed.
+
+Reusable workflows are inlined only when they use `workflow_call` and can be
+transformed into local jobs deterministically. Unsupported cases, unresolved
+refs, unsafe reusable workflows, and leftover remote `uses` fail closed.
+
+JavaScript actions, Docker actions, and `docker://` references are not bundled
+yet. They are pinned to locked SHAs as external dependencies.
+
+## API
+
+```ts
+import { diff, pack, scan, tree, update, verify, why } from 'actionspack'
+
+await pack()
+await update({ packageName: 'owner/repo', lockfileOnly: true })
+await verify()
+```
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/sxzz/sponsors/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/sxzz/sponsors/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+[MIT](./LICENSE) License © 2026-PRESENT [Kevin Deng](https://github.com/sxzz)
+
+<!-- Badges -->
+
+[npmx-version-src]: https://npmx.dev/api/registry/badge/version/actionspack
+[npmx-downloads-src]: https://npmx.dev/api/registry/badge/downloads-month/actionspack
+[npmx-href]: https://npmx.dev/actionspack
+[unit-test-src]: https://github.com/sxzz/actionspack/actions/workflows/unit-test.yml/badge.svg
+[unit-test-href]: https://github.com/sxzz/actionspack/actions/workflows/unit-test.yml

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { a as why, f as scan, i as update, l as verify, r as tree, s as pack, t as diff } from "./commands-CPJczWTq.mjs";
+import { styleText } from "node:util";
+import process from "node:process";
+import { cac } from "cac";
+//#endregion
+//#region src/cli.ts
+const cli = cac("actionspack");
+async function main() {
+	cli.command("", "Pack workflows").option("--entry <source:output>", "Use an explicit source/output workflow mapping").option("--external <selector>", "Pin a workflow or action without bundling it").action(async (flags) => {
+		await pack({
+			...normalizeConfigFlags(flags),
+			stderr: process.stderr,
+			stdout: process.stdout
+		});
+	});
+	cli.command("pack", "Pack workflows").option("--entry <source:output>", "Use an explicit source/output workflow mapping").option("--external <selector>", "Pin a workflow or action without bundling it").action(async (flags) => {
+		await pack({
+			...normalizeConfigFlags(flags),
+			stderr: process.stderr,
+			stdout: process.stdout
+		});
+	});
+	cli.command("scan", "Update the lockfile graph without generating workflows").option("--entry <source:output>", "Use an explicit source/output workflow mapping").option("--external <selector>", "Pin a workflow or action without bundling it").action(async (flags) => {
+		await scan({
+			...normalizeConfigFlags(flags),
+			stderr: process.stderr,
+			stdout: process.stdout
+		});
+	});
+	cli.command("update [packageName]", "Refresh locked dependency versions").option("--entry <source:output>", "Use an explicit source/output workflow mapping").option("--external <selector>", "Pin a workflow or action without bundling it").option("--lockfile-only", "Write only .github/workflow.lock.yml").action(async (packageName, flags) => {
+		const { lockfileOnly, ...rest } = flags;
+		await update({
+			...normalizeConfigFlags(rest),
+			packageName,
+			lockfileOnly,
+			stderr: process.stderr,
+			stdout: process.stdout
+		});
+	});
+	cli.command("tree", "Show the dependency tree from the lockfile").action(async () => {
+		await tree({ stdout: process.stdout });
+	});
+	cli.command("why <packageName>", "Explain why a dependency exists").action(async (packageName) => {
+		await why(packageName, { stdout: process.stdout });
+	});
+	cli.command("diff", "Show lockfile changes compared with HEAD").option("--json", "Print JSON output").action(async (flags) => {
+		await diff({
+			json: flags.json,
+			stdout: process.stdout
+		});
+	});
+	cli.command("verify", "Verify lockfile and packed workflows").action(async () => {
+		await verify();
+	});
+	cli.help();
+	cli.parse(process.argv, { run: false });
+	await cli.runMatchedCommand();
+}
+function normalizeConfigFlags(flags) {
+	return {
+		...flags.entry ? { entries: normalizeEntries(flags.entry) } : {},
+		...flags.external ? { external: normalizeStringList(flags.external) } : {}
+	};
+}
+function normalizeEntries(value) {
+	return normalizeStringList(value).map((item) => {
+		const [source, ...outputParts] = item.split(":");
+		const output = outputParts.join(":");
+		if (!source || !output) throw new Error(`Invalid --entry value: ${item}`);
+		return {
+			source,
+			output
+		};
+	});
+}
+function normalizeStringList(value) {
+	return Array.isArray(value) ? value : [value];
+}
+main().catch((error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`${styleText("red", `actionspack: ${message}`)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};