alunduil / alunduil/projects-v2-sync

npx projects-v2-sync <spec> runs a sync outside Actions

Offen
#7 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.