Skip to content

README.md

Latest commit

 

History

History
88 lines (61 loc) · 3.48 KB

README.md

File metadata and controls

88 lines (61 loc) · 3.48 KB
Raw

Apps

Applications and related projects are registered in apps/registry.yaml. Their on-disk path may live under any configured root (not only apps/).

This repo does not enforce web/desktop/cli folders. Each entry is a project directory with its own stack and docs.

Multi-folder roots

Full how-to (config fields, CLI examples, env overrides, common errors): docs/git/submodules.md.

Allowed parent folders for submodules are configured in scripts/submodule.config.json:

Key Default Meaning
roots apps, tutorials, skillsets, ai-infra Allowed top-level folders
defaultRoot apps Used when only a project name is given
org variableway GitHub org for inferred clone URLs
host github.com Git host for inferred URLs

Override without editing the file:

  • Env: SUBMODULE_ROOTS, SUBMODULE_DEFAULT_ROOT, SUBMODULE_ORG, SUBMODULE_HOST
  • CLI flags on the helper (below)

Local vs submodule

source in registry Meaning
local Code lives directly in this repo
submodule Linked git submodule (separate GitHub repo)

Add a submodule manually:

git submodule add https://github.com/<org>/<repo>.git apps/<project-name>
# or another configured root:
git submodule add https://github.com/<org>/<repo>.git tutorials/<project-name>

Then register it in apps/registry.yaml (set path to the actual folder) and keep .gitmodules in sync.

Or use the helper script:

# default root (apps/)
node scripts/add-submodule.mts <project-name>

# other configured root
node scripts/add-submodule.mts <project-name> --folder tutorials
node scripts/add-submodule.mts --path skillsets/devops-skill --repo https://github.com/qdriven/devops-skill.git

# explicit URL / org
node scripts/add-submodule.mts my-app --repo https://github.com/acme/my-app.git
node scripts/add-submodule.mts my-app --folder apps --org acme

Behavior:

  • Default repo URL: https://<host>/<org>/<project-name>.git (from config/CLI/env)
  • Path must be under an allowed roots entry
  • If the target folder already exists and is a git clone, and --repo was not passed, the script uses that folder's origin URL and runs git submodule add --force

Showcase site (planned)

apps/site can be the monorepo portal (apps list, registry metadata, GitHub Pages). It is not added yet.

Registry

apps/registry.yaml is the source of truth for app metadata. Indexed by scripts/generate-manifest.mjs → data/manifest.json.

path may be under any configured root, e.g. apps/innate-feeds or skillsets/devops-skill.

Recommended metadata fields per app entry:

Field Required Example Notes
name yes my-tool unique id
title yes My Tool display name
path yes apps/my-tool project path (any configured root)
source yes local / submodule code location mode
kind optional web, cli, desktop, service app type label (free-form)
tags optional [internal, mvp, ai-agent] multiple labels for search/filter
visibility optional public / private release intent
status optional planned / active lifecycle
repo submodule only https://github.com/org/repo source repository

Node apps under a registered path with a package.json can be pnpm workspace members when a root pnpm-workspace.yaml is present.