Merge pull request #7 from constructive-io/feat/update-deps-docs-and-fix-refs

docs: add update-deps documentation, fix hyperweb-io refs, add agent skill

Author: pyramation

.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:** <https://github.com/constructive-io/makage>  
+**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] <dest> [--flat] [--footer]` | Copy files with glob support |
+| `makage assets` | Copy LICENSE + package.json + README+FOOTER to dist |
+| `makage readme-footer --source <f> --footer <f> --dest <f>` | Concatenate README with footer |
+| `makage update-workspace` | Convert internal deps to `workspace:*` protocol |
+| `makage update-deps --from <source> --in <target>` | 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 <path-to-source-workspace> --in <path-to-target-repo>
+```
+
+### 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 `^<version>` directly in `package.json`
+6. Creates branch `deps-update/<name-or-timestamp>` 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 |

README.md

@@ -1,14 +1,14 @@
 # makage
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/hyperweb-io/makage/refs/heads/main/docs/img/logo.svg" width="80">
+  <img src="https://raw.githubusercontent.com/constructive-io/makage/refs/heads/main/docs/img/logo.svg" width="80">
   <br />
   Tiny build helper for monorepo packages
   <br />
-  <a href="https://github.com/hyperweb-io/makage/actions/workflows/ci.yml">
-    <img height="20" src="https://github.com/hyperweb-io/makage/actions/workflows/ci.yml/badge.svg" />
+  <a href="https://github.com/constructive-io/makage/actions/workflows/ci.yml">
+    <img height="20" src="https://github.com/constructive-io/makage/actions/workflows/ci.yml/badge.svg" />
   </a>
-  <a href="https://github.com/hyperweb-io/makage/blob/main/LICENSE">
+  <a href="https://github.com/constructive-io/makage/blob/main/LICENSE">
     <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg">
   </a>
 </p>
@@ -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 <source-workspace> --in <target-repo>
+```
+
+| 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 <packages...>` 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
 

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"
     },

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": {

packages/makage/README.md

@@ -1,14 +1,14 @@
 # makage
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/hyperweb-io/makage/refs/heads/main/docs/img/logo.svg" width="80">
+  <img src="https://raw.githubusercontent.com/constructive-io/makage/refs/heads/main/docs/img/logo.svg" width="80">
   <br />
   Tiny build helper for monorepo packages
   <br />
-  <a href="https://github.com/hyperweb-io/makage/actions/workflows/ci.yml">
-    <img height="20" src="https://github.com/hyperweb-io/makage/actions/workflows/ci.yml/badge.svg" />
+  <a href="https://github.com/constructive-io/makage/actions/workflows/ci.yml">
+    <img height="20" src="https://github.com/constructive-io/makage/actions/workflows/ci.yml/badge.svg" />
   </a>
-  <a href="https://github.com/hyperweb-io/makage/blob/main/LICENSE">
+  <a href="https://github.com/constructive-io/makage/blob/main/LICENSE">
     <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
   </a>
 </p>
@@ -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 <source> --in <target>`
+
+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
 

packages/makage/package.json

@@ -9,15 +9,15 @@
   "bin": {
     "makage": "cli.js"
   },
-  "homepage": "https://github.com/hyperweb-io/makage",
+  "homepage": "https://github.com/constructive-io/makage",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
     "directory": "dist"
   },
   "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",