alunduil / alunduil/projects-v2-sync
npx projects-v2-sync <spec> runs a sync outside Actions
- Vorherrschende Sprache
- TypeScript
- Sterne
- 0
- Forks
- 0
- Ø Merge
- 53 Min.
- Gemergte PRs (30 T.)
- 1
Beschreibung
## Summary
Add a command-line entry point taking the spec path as an argument, so a
sync can be run from a terminal without a workflow.
## Motivation
The bash implementation this replaces is runnable both ways. Its header
says so:
> Runs hourly from CI; safe to invoke locally — falls back to ambient `gh`
> auth when `GH_PROJECT_SYNC_TOKEN` is unset.
and it is invoked as `./scripts/sync-project.sh github/projects/inbox.json`.
Porting to an action drops that. Authoring a spec, checking what a sync
would touch, or reproducing a failed scheduled run would all mean pushing
a branch and waiting on a runner.
The scheduled job is also the hardest thing in this system to reproduce —
the sync token is not exposed to pull request runs, which is why
`sync-project.sh` carries an `ERR` trap and an xtrace block purely for CI
troubleshooting. A local entry point is the cheaper answer to the same
problem.
## A cheaper first step exists
GitHub ships [`@github/local-action`](https://github.com/github/local-action),
which runs an action's entry point locally against a `.env` file, and
`actions/typescript-action` commits a `.env.example` alongside it:
```console
npx @github/local-action . src/index.ts .env
```
That gets local execution without designing an argument surface, a token
fallback, or a second bundle. It does not satisfy this issue — the spec
still arrives as `INPUT_SPEC` in a `.env` rather than as an argument, and
it is a development tool rather than something to hand a user — but it
covers the reproduce-a-failed-run case immediately and is worth landing
first.
## Scope
- **Separate the entry points from the work.** `run()` currently reads its
own inputs (`src/main.ts:92-93` calls `readInputs()`, which reads
`INPUT_*`). Taking `Inputs` as a parameter lets the action entry supply
`readInputs()` and a CLI entry supply argv, with one copy of the sync.
- **A CLI entry** reading the spec path from argv, with usage and a
non-zero exit on failure. `sync-project.sh` exits `64` on a usage error;
worth keeping or deliberately dropping.
- **Token resolution without an input.** Match the bash fallback: an
explicit environment variable, otherwise ambient `gh` auth.
- **Terminal-appropriate output.** `@actions/core` emits workflow
commands, which are noise outside a runner. Running the current bundle
from a shell prints:
```console
$ INPUT_SPEC=spec.json INPUT_TOKEN=secret-value node dist/index.js
::add-mask::secret-value
Reading spec from spec.json
```
Decide whether the CLI routes reporting through something else, or
whether `::` lines are tolerable locally.
- **Packaging.** `package.json` has no `bin` and is `private: true`. Two
routes, and this issue should record which:
- `npx github:alunduil/projects-v2-sync ` needs only a `bin`
entry. `private` blocks `npm publish`, not a git install, and `dist/`
is committed so there is nothing to build on the consumer's machine.
- Publishing to npm gives the shorter `npx projects-v2-sync ` but
needs a package name, `private: false`, and a release workflow —
which overlaps the release work in #4.
The git route is the cheaper start and does not block the other later.
- **Bundle the CLI** the way the action entry is bundled, or document why
it runs from source.
## Acceptance criteria
- [ ] A documented `npx` invocation runs a sync against a spec path given
as an argument.
- [ ] The action and the CLI share one implementation; neither duplicates
the sync.
- [ ] The CLI resolves a token without one being passed on the command
line.
- [ ] A usage error and a sync failure both exit non-zero and say why.
- [ ] README documents the local invocation alongside the `uses:` example.
- [ ] Lint, typecheck, and tests pass, and `dist/` is current.
## Additional context
- Behaviour source: `scripts/sync-project.sh` in
alunduil/alunduil-infrastructure, which is the parity target for #3 and
the precedent for running locally.
- Adjacent to #4, which covers the Marketplace channel only. If npm
publishing is chosen here rather than the git route, the two release
paths should be decided together.
- `@github/local-action` covers the development half of this today; see
above.
- Most useful after #3 — until the reconciler lands the CLI can only
validate a spec — but the entry-point split is independent and can land
first.
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Rechercherichtung
Start at src/main.ts around lines 92-93 where run() calls readInputs(), then inspect package.json for bin/private settings and README for the current action usage. The change is done when a documented npx invocation accepts a spec argument, shares the action implementation, resolves auth without a CLI token, exits non-zero with useful messages, and lint/typecheck/tests plus dist/ pass.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- github-actions, node.js, typescript
- Bereich
- cli, developer-experience, tooling
- Issue-Typ
- Feature
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Aktiv
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 52/100