diff --git a/.agents/skills/makage-overview/SKILL.md b/.agents/skills/makage-overview/SKILL.md new file mode 100644 index 0000000..15b7c6a --- /dev/null +++ b/.agents/skills/makage-overview/SKILL.md @@ -0,0 +1,120 @@ +--- +name: makage-overview +description: Reference for the makage CLI tool — build helper, asset management, workspace updates, and cross-repo dependency synchronization. Use when asked about makage commands, monorepo builds, update-deps, or cross-repo dependency workflows. +--- + +# makage + +Tiny, zero-dependency build helper for monorepo packages. Replaces `cpy`, `rimraf`, and `copyfiles` with a single CLI. + +**Source:** +**npm:** `makage` (published from `packages/makage/dist`) + +## CLI Commands + +| Command | Description | +|---------|-------------| +| `makage build [--dev]` | Full build: clean + build-ts + assets. `--dev` adds `--declarationMap` | +| `makage clean [path...]` | Remove directories (defaults to `dist`) | +| `makage build-ts [--dev]` | TypeScript compilation for CJS + ESM | +| `makage copy [...sources] [--flat] [--footer]` | Copy files with glob support | +| `makage assets` | Copy LICENSE + package.json + README+FOOTER to dist | +| `makage readme-footer --source --footer --dest ` | Concatenate README with footer | +| `makage update-workspace` | Convert internal deps to `workspace:*` protocol | +| `makage update-deps --from --in ` | Cross-repo dependency detection (JSON output) | + +## Cross-Repo Dependency Updates (`update-deps`) + +### Purpose + +Deterministic, version-aware dependency synchronization across repositories. This is the engine behind the [constructive-hub update-constructive-deps workflow](https://github.com/constructive-io/constructive-hub/blob/main/.github/workflows/update-constructive-deps.yml). + +### Usage + +```bash +makage update-deps --from --in +``` + +### Algorithm + +1. Reads `pnpm-workspace.yaml` from `--from` to discover all packages + versions +2. Scans all `package.json` files in `--in` (supports workspace and non-workspace repos) +3. Cross-references dependencies/devDependencies/peerDependencies/optionalDependencies +4. Strips `^`/`~`/`>=` prefixes and compares semver parts numerically +5. Skips `workspace:` protocol deps (always in sync) +6. Outputs structured JSON to stdout; logs to stderr + +### JSON Output Schema + +```json +{ + "sourcePackages": [{ "name": "string", "version": "string", "path": "string" }], + "matchedPackages": [{ + "name": "string", + "currentVersion": "string", + "availableVersion": "string", + "depType": "dependencies | devDependencies | peerDependencies | optionalDependencies", + "consumer": "string", + "outdated": "boolean" + }], + "outdatedPackages": [/* subset of matchedPackages where outdated=true */], + "has_dep_changes": "boolean" +} +``` + +### CI Workflow Integration + +The `update-constructive-deps` workflow in `constructive-hub` runs per target repo: + +1. Checks out target repo + `constructive` workspace side by side +2. Runs `makage update-deps --from ./constructive --in .` +3. Parses JSON → extracts outdated package names +4. **Workspace repos** (`constructive-db`, `dashboard`, `pgpm-modules`, `dev-utils`): + - `echo "$OUTDATED_NAMES" | xargs pnpm update -r --latest` + - `pnpm install --no-frozen-lockfile` (sync lockfile) + - `pnpm -r build` (rebuild) +5. **Non-workspace repos** (`sandbox-templates`, `pgpm-boilerplates`): + - Per-directory: if lockfile exists → `pnpm update --latest $name` + - If no lockfile → `jq` to set `^` directly in `package.json` +6. Creates branch `deps-update/` and opens PR +7. For `constructive-db`: chains schema propagation via `repository_dispatch` + +### Triggers + +- **Manual** (`workflow_dispatch`): select which repos to update, optional PR name +- **Automatic** (`repository_dispatch: constructive-published`): fires when constructive publishes + +### Target Repos + +| Repo | Type | Default | +|------|------|---------| +| `constructive-db` | workspace | enabled (also triggers schema propagation) | +| `dashboard` | workspace | disabled | +| `pgpm-modules` | workspace | disabled | +| `dev-utils` | workspace | disabled | +| `sandbox-templates` | non-workspace | disabled | +| `pgpm-boilerplates` | non-workspace | disabled | + +## Monorepo Conventions + +makage assumes the following structure: + +- Build output in `dist/` +- pnpm workspace protocol for internal dependencies +- `publishConfig.directory` set to `dist` in `package.json` +- Shared `LICENSE` at monorepo root +- Optional `FOOTER.md` per package (appended to README before publish) + +## Key Files + +| Path | Purpose | +|------|---------| +| `packages/makage/src/cli.ts` | CLI entrypoint and command dispatch | +| `packages/makage/src/commands/updateDeps.ts` | Cross-repo dependency detection logic | +| `packages/makage/src/commands/updateWorkspace.ts` | Workspace protocol updater | +| `packages/makage/src/commands/build.ts` | Build orchestration | +| `packages/makage/src/commands/copy.ts` | File copy with glob + flatten | +| `packages/makage/src/commands/clean.ts` | Directory removal | +| `packages/makage/src/commands/assets.ts` | Asset copy helper | +| `packages/makage/src/commands/buildTs.ts` | TypeScript CJS + ESM compilation | +| `packages/makage/src/commands/readmeFooter.ts` | README + FOOTER concatenation | diff --git a/README.md b/README.md index 0517793..9d083fd 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # makage

- +
Tiny build helper for monorepo packages
- - + + - +

@@ -146,8 +146,69 @@ makage readme-footer --source README.md --footer FOOTER.md --dest dist/README.md # Update workspace dependencies makage update-workspace + +# Detect outdated cross-repo dependencies (structured JSON output) +makage update-deps --from ./constructive --in . +``` + +## Cross-Repo Dependency Updates (`update-deps`) + +The `update-deps` command enables deterministic, version-aware dependency synchronization across repositories. It is the engine behind the [constructive-hub update-constructive-deps workflow](https://github.com/constructive-io/constructive-hub/blob/main/.github/workflows/update-constructive-deps.yml). + +### How it works + +1. **Discovers** all packages in a source pnpm workspace (by reading `pnpm-workspace.yaml`) +2. **Scans** the target repo's `package.json` files (supports both monorepo and non-workspace layouts) +3. **Cross-references** dependencies to find packages that exist in both source and target +4. **Compares versions** using semver to identify outdated packages +5. **Outputs structured JSON** to stdout for CI consumption (logs go to stderr) + +### Usage + +```bash +makage update-deps --from --in +``` + +| Flag | Description | +|------|-------------| +| `--from` | Path to the source pnpm workspace (contains `pnpm-workspace.yaml`) | +| `--in` | Path to the target repo to scan for outdated deps | + +### Output format + +```json +{ + "sourcePackages": [{ "name": "@constructive/foo", "version": "1.2.3", "path": "packages/foo" }], + "matchedPackages": [{ "name": "@constructive/foo", "currentVersion": "^1.1.0", "availableVersion": "1.2.3", "depType": "dependencies", "consumer": "@myapp/bar", "outdated": true }], + "outdatedPackages": [/* subset of matchedPackages where outdated=true */], + "has_dep_changes": true +} ``` +### CI Integration + +The `update-deps` command is used in GitHub Actions to automatically update downstream repos when the source workspace publishes new versions. The typical CI flow: + +1. Check out the target repo + source workspace side by side +2. Run `makage update-deps --from ./constructive --in .` for structured JSON detection +3. Parse the JSON output to extract outdated package names +4. Run `pnpm update -r --latest ` to update them +5. Create a PR with the results + +Target repos are categorized into two strategies: +- **Workspace repos** (have `pnpm-workspace.yaml`): Use `pnpm update -r --latest` for bulk updates +- **Non-workspace repos** (e.g., template repos): Update each `package.json` individually via `jq` or per-directory `pnpm update` + +### Supported target repos + +The constructive-hub workflow currently updates: +- `constructive-db` (default, also triggers schema propagation) +- `dashboard` +- `pgpm-modules` +- `dev-utils` +- `sandbox-templates` +- `pgpm-boilerplates` + ## Documentation For detailed usage and API documentation, see [packages/makage/README.md](./packages/makage/README.md). @@ -159,7 +220,7 @@ For detailed usage and API documentation, see [packages/makage/README.md](./pack 1. Clone the repository: ```bash -git clone https://github.com/hyperweb-io/makage.git +git clone https://github.com/constructive-io/makage.git ``` 2. Install dependencies: @@ -180,7 +241,7 @@ pnpm test:watch ## Credits Built for developers, with developers. -👉 https://launchql.com | https://hyperweb.io +👉 https://constructive.io ## Disclaimer diff --git a/lerna.json b/lerna.json index 83b3327..c6d83d9 100644 --- a/lerna.json +++ b/lerna.json @@ -11,7 +11,7 @@ "registry": "https://registry.npmjs.org", "command": { "create": { - "homepage": "https://github.com/hyperweb-io/makage", + "homepage": "https://github.com/constructive-io/makage", "license": "MIT", "access": "restricted" }, diff --git a/package.json b/package.json index 8eab3a1..53aeba5 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "private": true, "repository": { "type": "git", - "url": "https://github.com/hyperweb-io/makage" + "url": "https://github.com/constructive-io/makage" }, "license": "MIT", "publishConfig": { diff --git a/packages/makage/README.md b/packages/makage/README.md index 1980b2d..baa4f28 100644 --- a/packages/makage/README.md +++ b/packages/makage/README.md @@ -1,14 +1,14 @@ # makage

- +
Tiny build helper for monorepo packages
- - + + - +

@@ -248,6 +248,38 @@ This will: 3. Update all dependencies, devDependencies, peerDependencies, and optionalDependencies 4. Convert version numbers to `workspace:*` for internal packages +### `makage update-deps --from --in ` + +Detects outdated cross-repo dependencies by comparing a source pnpm workspace against a target repo. Outputs structured JSON to stdout for CI integration. + +```bash +makage update-deps --from ./constructive --in . +``` + +| Flag | Description | +|------|-------------| +| `--from` | Path to the source pnpm workspace (must contain `pnpm-workspace.yaml`) | +| `--in` | Path to the target repo to scan for outdated deps | + +**How it works:** +1. Reads `pnpm-workspace.yaml` from the source to discover all published packages and their versions +2. Scans all `package.json` files in the target repo (workspace-aware or recursive scan) +3. Cross-references `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies` +4. Compares version strings (strips `^`/`~` prefixes) to determine what's outdated +5. Outputs a JSON result with `sourcePackages`, `matchedPackages`, `outdatedPackages`, and `has_dep_changes` + +**Output format:** +```json +{ + "sourcePackages": [{ "name": "@constructive/foo", "version": "1.2.3", "path": "packages/foo" }], + "matchedPackages": [{ "name": "@constructive/foo", "currentVersion": "^1.1.0", "availableVersion": "1.2.3", "depType": "dependencies", "consumer": "@myapp/bar", "outdated": true }], + "outdatedPackages": [/* subset where outdated=true */], + "has_dep_changes": true +} +``` + +This command powers the [constructive-hub update-constructive-deps workflow](https://github.com/constructive-io/constructive-hub/blob/main/.github/workflows/update-constructive-deps.yml) which automatically creates PRs in downstream repos when the constructive workspace publishes new package versions. + ## Why makage? Most monorepo packages need the same basic build operations: @@ -264,7 +296,7 @@ Instead of installing multiple dependencies (`cpy`, `rimraf`, etc.) in every pac 1. Clone the repository: ```bash -git clone https://github.com/hyperweb-io/makage.git +git clone https://github.com/constructive-io/makage.git ``` 2. Install dependencies: @@ -285,7 +317,7 @@ pnpm test:watch ## Credits Built for developers, with developers. -👉 https://launchql.com | https://hyperweb.io +👉 https://constructive.io ## Disclaimer diff --git a/packages/makage/package.json b/packages/makage/package.json index 414bf57..a957e59 100644 --- a/packages/makage/package.json +++ b/packages/makage/package.json @@ -9,7 +9,7 @@ "bin": { "makage": "cli.js" }, - "homepage": "https://github.com/hyperweb-io/makage", + "homepage": "https://github.com/constructive-io/makage", "license": "MIT", "publishConfig": { "access": "public", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "https://github.com/hyperweb-io/makage" + "url": "https://github.com/constructive-io/makage" }, "keywords": [ "build", @@ -29,7 +29,7 @@ "package-management" ], "bugs": { - "url": "https://github.com/hyperweb-io/makage/issues" + "url": "https://github.com/constructive-io/makage/issues" }, "dependencies": { "glob": "^11.0.0",