From 8455b69a819dc9cf2a85e547186204b249c89cfd Mon Sep 17 00:00:00 2001 From: Daniel Clayton Date: Mon, 2 Mar 2026 19:43:11 -0700 Subject: [PATCH 1/2] docs: expand npm package documentation for core and cli --- .changeset/green-coats-share.md | 6 ++++ packages/cli/README.md | 46 ++++++++++++++++++++++++++--- packages/core/README.md | 51 +++++++++++++++++++++++++++++++-- 3 files changed, 96 insertions(+), 7 deletions(-) create mode 100644 .changeset/green-coats-share.md diff --git a/.changeset/green-coats-share.md b/.changeset/green-coats-share.md new file mode 100644 index 0000000..783dc90 --- /dev/null +++ b/.changeset/green-coats-share.md @@ -0,0 +1,6 @@ +--- +"@dotgithub/core": patch +"@dotgithub/cli": patch +--- + +Improve npm package documentation for both core and CLI with clearer usage examples, command flows, and direct documentation links. diff --git a/packages/cli/README.md b/packages/cli/README.md index d022032..ef3110a 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,16 +1,54 @@ # @dotgithub/cli -CLI for DotGitHub workflow scaffolding and synthesis. +CLI for scaffolding, managing, and synthesizing DotGitHub workflows. ## Install ```bash npm install -g @dotgithub/cli -# or +``` + +Or run without installing globally: + +```bash npx @dotgithub/cli --help ``` +## Commands (quick overview) + +```bash +# Initialize DotGitHub config/files +dotgithub init + +# Add pinned GitHub Actions to your config +dotgithub add actions/checkout@v4 + +# Generate workflow files +dotgithub synth +``` + +Aliases: + +```bash +dgh --help +dotgithub --help +``` + +## Typical flow + +1. `dotgithub init` +2. `dotgithub add ` +3. author/update your workflow constructs/config +4. `dotgithub synth` +5. commit generated workflow files + ## Docs -- -- +- Main docs: +- Guides: +- CLI source/context: + +## Repository + +- Source: +- Issues: diff --git a/packages/core/README.md b/packages/core/README.md index 3208354..6598172 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,6 +1,16 @@ # @dotgithub/core -Core library for DotGitHub: type-safe constructs and workflow generation utilities. +Type-safe core library for generating GitHub Actions workflows with DotGitHub constructs. + +## What this package is + +`@dotgithub/core` is the programmatic engine behind DotGitHub. It provides: + +- strongly typed workflow models +- construct primitives for jobs/workflows/shared workflows +- generation/synthesis helpers for writing `.github/workflows/*.yml` + +If you want to build reusable workflow logic in code, this is the package you use. ## Install @@ -8,7 +18,42 @@ Core library for DotGitHub: type-safe constructs and workflow generation utiliti npm install @dotgithub/core ``` +## Quick example + +```ts +import { createWorkflow } from '@dotgithub/core'; + +const workflow = createWorkflow({ + on: { + push: { branches: ['main'] }, + }, + jobs: { + test: { + 'runs-on': 'ubuntu-latest', + steps: [ + { uses: 'actions/checkout@v4' }, + { run: 'npm ci' }, + { run: 'npm test' }, + ], + }, + }, +}); + +// synthesize with your DotGitHub pipeline +``` + +## When to use `@dotgithub/core` vs `@dotgithub/cli` + +- Use **`@dotgithub/core`** for library/SDK style usage in code. +- Use **`@dotgithub/cli`** when you want command-driven setup and synthesis. + ## Docs -- -- +- Main docs: +- Guides: +- API/reference context: + +## Repository + +- Source: +- Issues: From c03583bd3d490c5b85959e046140372735fd797a Mon Sep 17 00:00:00 2001 From: Daniel Clayton Date: Mon, 2 Mar 2026 19:45:32 -0700 Subject: [PATCH 2/2] docs: emphasize TypeScript authoring workflow in package descriptions --- packages/cli/README.md | 8 ++++---- packages/core/README.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index ef3110a..915ee0e 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,6 +1,6 @@ # @dotgithub/cli -CLI for scaffolding, managing, and synthesizing DotGitHub workflows. +CLI for scaffolding, managing, and synthesizing DotGitHub workflows from TypeScript definitions. ## Install @@ -34,12 +34,12 @@ dgh --help dotgithub --help ``` -## Typical flow +## Typical TypeScript workflow 1. `dotgithub init` 2. `dotgithub add ` -3. author/update your workflow constructs/config -4. `dotgithub synth` +3. author/update your workflow constructs in **TypeScript** +4. `dotgithub synth` to generate YAML 5. commit generated workflow files ## Docs diff --git a/packages/core/README.md b/packages/core/README.md index 6598172..3458bdc 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,6 +1,6 @@ # @dotgithub/core -Type-safe core library for generating GitHub Actions workflows with DotGitHub constructs. +Type-safe TypeScript library for defining and generating GitHub Actions workflows using DotGitHub constructs. ## What this package is @@ -10,7 +10,7 @@ Type-safe core library for generating GitHub Actions workflows with DotGitHub co - construct primitives for jobs/workflows/shared workflows - generation/synthesis helpers for writing `.github/workflows/*.yml` -If you want to build reusable workflow logic in code, this is the package you use. +If you want to author reusable CI/CD logic in TypeScript (instead of hand-writing YAML), this is the package you use. ## Install