feat(skills): add cozy-external-app skill for scaffolding external apps

[kitsunoff]

Summary

• Add cozy-external-app skill that scaffolds a complete Cozystack external app package
• Generates chart skeleton (Chart.yaml, Makefile, values.yaml with cozyvalues-gen annotations, templates)
• Registers the app in core/platform (namespace, HelmRelease, CozystackResourceDefinition)
• Handles dependency integration with two patterns: managed CNPG Postgres clusters provisioned in-chart, and external secret references for pre-existing services
• CNPG integration patterns verified against cozystack harbor/keycloak implementations
• Register the new plugin in marketplace.json and update README

Changes

• skills/cozy-external-app/.claude-plugin/plugin.json — plugin metadata
• skills/cozy-external-app/skills/cozy-external-app/SKILL.md — 10-phase skill with Guardrails and References
• .claude-plugin/marketplace.json — added plugin entry
• README.md — added table row

Summary by CodeRabbit

• New Features

  • Added a new cozy-external-app plugin that scaffolds external Cozystack application packages via an interactive, multi-phase generate-only workflow with pre-flight checks, confirmation gates, and multiple dependency-integration patterns (e.g., operator-managed, in-chart, or external wiring).

• Documentation

  • Updated Plugins list with an entry describing the new cozy-external-app skill.

[coderabbitai]

Warning

Rate limit exceeded

@kitsunoff has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 28 minutes and 3 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 28 minutes and 3 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ac6ee68d-dfb6-4dc8-ba0e-0127f20b5350

📥 Commits

Reviewing files that changed from the base of the PR and between fccbbd5 and 34c04ad.

📒 Files selected for processing (3)

• .claude-plugin/marketplace.json
• README.md
• skills/cozy-external-app/skills/cozy-external-app/SKILL.md

📝 Walkthrough

Walkthrough

Adds a new cozy-external-app Claude plugin: marketplace registration, plugin metadata, README entry, and a comprehensive generate-only skill spec that defines a multi-phase CLI workflow for scaffolding Cozystack external app packages, dependency contract resolution, chart/template generation, and platform registration.

Changes

Cohort / File(s)	Summary
Marketplace & Plugin metadata ​.claude-plugin/marketplace.json, skills/cozy-external-app/.claude-plugin/plugin.json	Register new plugin cozy-external-app with source ./skills/cozy-external-app, metadata (name, version 1.0.0, description, author).
Documentation README.md	Add README table entry for cozy-external-app under Skills.
Skill specification skills/cozy-external-app/skills/cozy-external-app/SKILL.md	Add full generate-only skill spec: CLI args, preflight checks (local/gh/kubectl), interactive prompts, dependency contract resolution (three integration patterns), deterministic Helm chart skeleton and templates, platform registration updates, validation, and guardrails.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant CLI as CLI Parser
    participant Preflight as Preflight Validator
    participant DepResolver as Dependency Resolver
    participant Generator as Template Generator
    participant FS as File System
    participant SchemaVal as Schema Validator

    User->>CLI: invoke cozy-external-app (app-name, flags)
    CLI->>Preflight: parse args & run repo/tool checks
    Preflight-->>CLI: preflight result

    CLI->>DepResolver: resolve dependencies (local/gh/kubectl)
    DepResolver-->>CLI: dependency contracts & wiring options

    CLI->>User: interactive prompts for app & wiring
    User-->>CLI: approve plan

    CLI->>Generator: generate chart skeleton & templates
    Generator->>FS: write Chart.yaml, values, templates, platform entries
    FS-->>Generator: confirm files written

    Generator->>SchemaVal: validate schemas & manifests
    SchemaVal-->>CLI: validation results
    CLI->>User: summary & next steps

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hop with charts and tiny maps,
Scaffolding apps in tidy scraps.
With contracts checked and files in place,
Cozy packages spring to grace.
Hooray — a new app finds its space!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(skills): add cozy-external-app skill for scaffolding external apps' clearly and accurately summarizes the main change—adding a new skill for scaffolding external apps, matching the comprehensive changeset that includes the skill definition, plugin metadata, and documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces the cozy-external-app skill, which provides a structured workflow for scaffolding external application packages within the Cozystack ecosystem. The skill automates the creation of Helm charts, templates, and platform registration files while handling dependency patterns like managed Postgres clusters. The review feedback highlights several opportunities to strengthen the skill's logic, specifically by ensuring all required metadata for resource definitions is collected, clarifying the process for gathering operator chart details, providing explicit template examples for upstream Helm charts, and maintaining correct YAML formatting and variable consistency during the registration phase.

[gemini-code-assist]

Phase 3 is missing several metadata fields required for the CozystackResourceDefinition in Phase 8. Specifically, the skill needs to gather the app's display name, description, category, tags, and the Kubernetes Kind/Plural names for the resource.

Suggested change

	5. **Icon**: path to an SVG file for the dashboard. If not available yet, note it — Phase 6 will create a `logos/` placeholder and Phase 9 will fail until the user provides one.
	5. **Icon**: path to an SVG file for the dashboard. If not available yet, note it — Phase 6 will create a `logos/` placeholder and Phase 9 will fail until the user provides one.
	6. **Metadata**: Display Name (e.g., `Immich`), Description (e.g., `Self-hosted photo and video management solution`), Category (e.g., `Media`), and Tags (e.g., `photo, video`).
	7. **Resource Definition**: Kind (e.g., `Immich`) and Plural (e.g., `immichs`) for the CozystackResourceDefinition.

[gemini-code-assist]

Phase 5 uses $OPERATOR_CHART_NAME and $OPERATOR_CHART_VERSION in the generated Makefile, but these variables are never gathered from the user. If an operator is required, the skill should ask for the specific chart name and version within the repository.

Suggested change

	If an operator is needed, create `packages/system/$APP_NAME-operator/`:
	If an operator is needed, use `AskUserQuestion` to collect the operator's chart name and version from the provided repository URL. Then create `packages/system/$APP_NAME-operator/`:

[gemini-code-assist]

The skill mentions wrapping upstream charts in a Flux HelmRelease but only provides a template for a direct Deployment. Providing a HelmRelease template example will help the AI generate the correct structure for the 'upstream chart' case.

Suggested change

	Generate the primary workload template. If the user chose "upstream Helm chart", wrap it in a Flux HelmRelease (like harbor does). If "custom templates", create a Deployment or StatefulSet directly.
	**For a Flux HelmRelease wrapper example:**
	```yaml
	apiVersion: helm.toolkit.fluxcd.io/v2
	kind: HelmRelease
	metadata:
	name: {{ .Release.Name }}
	spec:
	interval: 1h
	chart:
	spec:
	chart: $UPSTREAM_CHART_NAME
	version: $UPSTREAM_CHART_VERSION
	sourceRef:
	kind: HelmRepository
	name: $UPSTREAM_REPO_NAME
	values:
	# Map values from .Values to upstream chart values

[gemini-code-assist]

The sourceRef.name is hardcoded to external-apps, but Phase 8 later includes logic to extract the actual name from init.yaml. The template should use the variable extracted from init.yaml to ensure consistency if the user has renamed their repository.

Suggested change

	name: external-apps
	name: $GIT_REPO_NAME

[gemini-code-assist]

When injecting the values.schema.json content into the CozystackResourceDefinition, the AI must be instructed to indent the JSON content correctly to maintain valid YAML structure.

Suggested change

	<contents of values.schema.json>
	<contents of values.schema.json, indented by 6 spaces>

[kitsunoff]

Self-review after two parallel analyses. Three concrete correctness issues will bite anyone running the skill end-to-end and should be fixed before merge; four smaller items are non-blocking. Overall architecture (contract-driven Pattern C, runtime resolution, Phase 5.5 plan gate) checks out against the actual cozystack and external-apps-example sources.

Blocker scope: generated charts would fail helm template (missing values), silently rotate DB passwords on every reconcile (random regeneration without lookup), or pick the wrong GitRepository name from init.yaml. All three are one-line fixes.

[kitsunoff]

Blocker: randAlphaNum 32 produces a fresh random value every helm template or Flux reconcile. When .Values.database.password is empty (the default — Phase 6 never declares the field), each render writes a different password into the Postgres CR, which cascades into the downstream postgres-<cr>-credentials Secret and breaks the running app whenever its password rotates.

Evidence: cozystack/packages/apps/postgres/templates/init-script.yaml solves this with Sprig's lookup — pulls the existing password from the already-rendered Secret and reuses it on subsequent renders. The Pattern A redis example in this skill uses the same idiom.

Fix: wrap the password with lookup so subsequent renders reuse the previously-rendered value:

{{- $existing := lookup "v1" "Secret" .Release.Namespace (printf "postgres-%s-db-credentials" .Release.Name) }}
{{- $pwd := "" }}
{{- if $existing }}
{{-   $pwd = index $existing.data .Values.database.user | b64dec }}
{{- end }}
{{- $pwd = $pwd | default (.Values.database.password | default (randAlphaNum 32)) }}
...
    password: {{ $pwd | quote }}

Same fix needed in the Dependency catalog Pattern C postgres snippet around line 1024.

[kitsunoff]

Blocker: Phase 7 Pattern C postgres.yaml (line ~581) reads .Values.database.{size,replicas,user,name,password} and Pattern C redis.yaml (line ~620) reads .Values.redis.{size,replicas}. This values.yaml example only documents Pattern A (database.{size,replicas} without user/name) and Pattern B. A user who follows the skill end-to-end on Pattern C — the documented default for external apps — ends up with a chart that fails helm template: <no value> in every wired gitea.config.database.* path, plus the Postgres CR spec renders with empty users: and databases: maps.

Fix: add a Pattern C values section alongside Pattern A and Pattern B. Minimum fields for postgres: user, name, size, replicas with sane defaults. For redis: size, replicas. Document that password is optional and generated when empty (ties to blocker #1).

Test: generate a chart for /cozy-external-app gitea --depends-on=postgres,redis on Pattern C defaults and run helm template test . — must render without <no value> anywhere.

[kitsunoff]

Blocker: yq -r '.metadata.name' $REPO_DIR/init.yaml | head -1 treats any metadata.name from any document as authoritative. The reference init.yaml in cozystack/external-apps-example contains both a GitRepository and a HelmRelease both named external-apps — the extraction works by coincidence. If a user renames their repo so the two differ (e.g., GitRepository my-apps, HelmRelease my-apps-release, which is a valid layout), head -1 silently grabs the HelmRelease name and every Phase 8 sourceRef points at a non-existent source.

The skill already documents the safe form directly below (line 758) as a "fallback for multi-document init.yaml":

yq -r 'select(.kind == "GitRepository") | .metadata.name' $REPO_DIR/init.yaml

Fix: promote that form to the only/primary path. It handles the single-document case equally well.

[kitsunoff]

Observation (non-blocking): this bash snippet uses short flags (-v -s -r) while the Makefile generated a few lines up (line 311) uses long flags (--values --schema --readme). The global convention is long-flag-only. Since users literally copy this command, consistency with the Makefile matters. Normalize to long form here.

[kitsunoff]

Observation (non-blocking): a literal-minded assistant may emit the # type: oci line as a comment rather than uncommenting it. The reference external-apps-example's helmrepositories.yaml has type: oci set plainly when the source is OCI. Consider two explicit variants in the skill (HTTPS source vs OCI source) or a Go-template conditional so the emitted YAML never needs post-processing.

[kitsunoff]

Observation (non-blocking): the clause "or detectable as a sibling dir of $REPO_DIR" is never defined. Phase 2 Step 4 only reads $COZYSTACK_REPO from env. Either specify the probe (e.g., check ../cozystack/packages/system/ for cozyrds directories) or drop the clause.

[kitsunoff]

Observation (non-blocking): functionally correct — mymaster is Spotahome's default sentinel monitor name and cozystack's packages/apps/redis/templates/redisfailover.yaml does not override it. But the skill's own guardrail says "never guess a dependency's Secret/config names" and this value is not derivable from $DEP_CONTRACT. Add a one-line comment citing the Spotahome default so an assistant or reviewer can tell verified from guessed.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/cozy-external-app/skills/cozy-external-app/SKILL.md`:
- Around line 474-484: Replace the hardcoded dependsOn and subchart toggles (the
dependsOn block plus values keys postgresql, postgresql-ha, redis,
redis-cluster) with logic that constructs those entries from the Phase 4
resolved dependency list and the detected upstream subcharts: iterate the
resolved dependencies and emit a dependsOn entry for each backing service (using
the release name/namespace templating currently used), and iterate detected
upstream subcharts to set values.<chart>.enabled = false only for the subcharts
that actually exist; skip others so HelmRelease output matches actual deps.
Ensure the code that builds the HelmRelease uses the Phase 4
resolvedDependencies data structure and the upstreamSubcharts detection result
rather than fixed names.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 27c70102-e082-451b-b46d-8b402aa35531

📥 Commits

Reviewing files that changed from the base of the PR and between 1d748bc and 5c8aaf1.

📒 Files selected for processing (4)

• .claude-plugin/marketplace.json
• README.md
• skills/cozy-external-app/.claude-plugin/plugin.json
• skills/cozy-external-app/skills/cozy-external-app/SKILL.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Make dependency wiring dynamic instead of hardcoded postgres/redis.

Lines 474-484 hardcode dependsOn and subchart toggles for postgres/redis. For apps without those deps (or with different deps), this generates incorrect HelmRelease output. Build these blocks from the Phase 4 resolved dependency list and detected upstream subcharts.

Suggested adjustment

-  dependsOn:
-    - name: postgres-{{ .Release.Name }}-db
-      namespace: {{ .Release.Namespace }}
-    - name: redis-{{ .Release.Name }}-redis
-      namespace: {{ .Release.Namespace }}
+  # Emit dependsOn entries only for dependencies selected in Phase 4 (Pattern C/A),
+  # using each dependency's resolved release prefix and CR name template.

-  values:
-    postgresql:    { enabled: false }
-    postgresql-ha: { enabled: false }
-    redis:         { enabled: false }
-    redis-cluster: { enabled: false }
+  values:
+    # Disable only subcharts that were actually detected in Phase 4 Step 1
+    # and mapped to external/sibling dependency wiring.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/cozy-external-app/skills/cozy-external-app/SKILL.md` around lines 474
- 484, Replace the hardcoded dependsOn and subchart toggles (the dependsOn block
plus values keys postgresql, postgresql-ha, redis, redis-cluster) with logic
that constructs those entries from the Phase 4 resolved dependency list and the
detected upstream subcharts: iterate the resolved dependencies and emit a
dependsOn entry for each backing service (using the release name/namespace
templating currently used), and iterate detected upstream subcharts to set
values.<chart>.enabled = false only for the subcharts that actually exist; skip
others so HelmRelease output matches actual deps. Ensure the code that builds
the HelmRelease uses the Phase 4 resolvedDependencies data structure and the
upstreamSubcharts detection result rather than fixed names.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/cozy-external-app/skills/cozy-external-app/SKILL.md`:
- Around line 214-215: The contract for $SOURCE_REPO_TYPE is inconsistent: Phase
5 documentation says non-OCI should be left empty while Phase 8 (and the
HelmRepository template condition) expects "https", which causes wrong variant
selection; update the Phase 8 text/examples and any condition checks that
reference $SOURCE_REPO_TYPE (the Phase 8 rendering logic and the HelmRepository
template branch) to treat non-OCI as empty (or conversely make Phase 5 use
"https" everywhere) so both collection and rendering agree—pick the
empty-as-default approach and replace "https" examples/conditions in Phase 8 and
related template branches with empty/default handling for $SOURCE_REPO_TYPE.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 18cdd063-21b3-4ebf-8db6-8669b1769f83

📥 Commits

Reviewing files that changed from the base of the PR and between 5c8aaf1 and fccbbd5.

📒 Files selected for processing (1)

• skills/cozy-external-app/skills/cozy-external-app/SKILL.md