feat: Added action, package-managers, tart, terraform, ollama, and files. Added new skill for generating examples

Author: kevinwang5658

.claude/commands/add-examples.md

@@ -0,0 +1,61 @@
+# add-examples
+
+Add `defaultConfig` and `exampleConfigs` to a Codify resource.
+
+## Instructions
+
+The user will either pass a file path as an argument (`$ARGUMENTS`) or have a file open in the IDE. Read the resource file, then follow the rules below to add `defaultConfig` and `exampleConfigs`.
+
+If `$ARGUMENTS` is provided, use that file path. Otherwise use the file the user has open.
+
+### Step 1 — Read the resource
+
+Read the resource file. Identify:
+- The config interface/type (fields, which are required vs optional)
+- `operatingSystems` declared in `getSettings()` — determines whether to add `os` to examples
+- `dependencies` — used to decide whether to show a multi-resource example
+- Any existing `defaultConfig` or `exampleConfigs` (update rather than duplicate)
+
+If the schema is a separate JSON file, read it too.
+
+Also check for sibling resources that are commonly used together (e.g. if this resource `dependsOn` another type, read that type's file to understand its config shape).
+
+### Step 2 — Add `defaultConfig`
+
+Rules:
+- Type: `Partial<TheConfig>` (never include `os` — it's not on the typed config interface)
+- For required fields with no sensible default: use the placeholder string `'<Replace me here!'>`
+- For optional arrays that default to empty: set to `[]`
+- Omit fields that are purely user-specific (paths, names, credentials)
+- Use the tool's own documented defaults where applicable
+
+### Step 3 — Add `exampleConfigs`
+
+Rules:
+- Up to two examples: `example1` and `example2`
+- **No trivial examples** — every example must have meaningful configuration, not just `{ type: 'foo' }` with no parameters
+- `example1`: the most common real-world use case with substantive config values
+- `example2`: a more advanced variant OR a multi-resource example showing full end-to-end setup; multi-resource is preferred when the resource `dependsOn` another
+- Every example needs a `title` (short noun-phrase) and a `description` (one sentence)
+- Use realistic placeholder values for sensitive fields (`'<Replace me here!'>`), not real credentials
+- Do not add step-numbering in descriptions
+
+**`os` field in examples:**
+- The `os` field values come from the `ResourceOs` enum in `@codifycli/schemas` (`../codify-schemas/src/types/index.ts`): `'macOS'`, `'linux'`, `'windows'`
+- Add `os` to config entries inside examples only when `operatingSystems` is restricted to a single OS (e.g. Darwin-only → `os: ['macOS']`, Linux-only → `os: ['linux']`)
+- Skip `os` entirely when the resource supports both Darwin and Linux
+
+**Shared examples:**
+- When a multi-resource example is used across multiple related resources (e.g. asdf + asdf-plugin + asdf-install), define it once in a shared `examples.ts` file in the resource folder and spread it in with `...exampleSharedConfigs`
+
+### Step 4 — Import `ExampleConfig`
+
+Add `ExampleConfig` to the existing `@codifycli/plugin-core` import if not already present.
+
+### Step 5 — Register in `getSettings()`
+
+Add `defaultConfig` and `exampleConfigs` fields inside the object returned by `getSettings()`, before `operatingSystems`.
+
+## Output format
+
+Make all edits directly to the file. Do not summarise every line changed — just briefly confirm what was added.

CLAUDE.md

@@ -383,16 +383,17 @@ Every resource should have a `defaultConfig` and `exampleConfigs`. These are sur
 - For required fields with no sensible default (e.g. `deviceId`, `plugin`, `awsAccessKeyId`), use the placeholder string `'<Replace me here!'>`
 - For optional array fields that default to empty (e.g. `plugins`, `aliases`, `paths`), set them to `[]`
 - Omit fields that are purely user-specific (e.g. paths, names, credentials) — don't guess
-- If the resource declares `operatingSystems: [OS.Darwin]` or `operatingSystems: [OS.Linux]` (i.e. only one OS, not both), do NOT add `os` to `defaultConfig` (it's not on the typed config interface). Instead, add `os: ['darwin']` or `os: ['linux']` only to the config entries inside `exampleConfigs`. Skip entirely when the resource supports both OS.
+- If the resource declares `operatingSystems: [OS.Darwin]` or `operatingSystems: [OS.Linux]` (i.e. only one OS, not both), do NOT add `os` to `defaultConfig` (it's not on the typed config interface). Instead, add the correct `os` value only to the config entries inside `exampleConfigs`. Skip entirely when the resource supports both OS.
+- The `os` field values come from the `ResourceOs` enum in `@codifycli/schemas` (`../codify-schemas/src/types/index.ts`): use `'macOS'` for Darwin, `'linux'` for Linux, `'windows'` for Windows (e.g. `os: ['macOS']`, not `os: ['darwin']`).
 
 **`exampleConfigs`** — up to two named examples (`example1`, `example2`):
-- `example1`: a minimal, focused single-resource example showing the most common use case
+- `example1`: a substantive example showing the most common real-world use case with meaningful configuration — not a trivial "just install it" with no parameters
 - `example2`: either a more advanced single-resource variant, OR a multi-resource example that shows the full end-to-end setup (e.g. install the tool + configure it)
 - Multi-resource examples (configs array with multiple types) are especially useful when the resource `dependsOn` another — show installing the dependency too
 - Every example needs a `title` (short, noun-phrase) and a `description` (one sentence explaining what it does and why)
 - Use realistic but obviously-placeholder values for sensitive fields (`'<Replace me here!'>`), not real credentials
 - Don't add step-numbering ("Step 1 of 3") in descriptions — it doesn't make sense when viewed from a single resource page
-- If the resource is OS-specific (only Darwin or only Linux), add `os: ['darwin']` or `os: ['linux']` to each config entry in the example so the editor filters it correctly
+- If the resource is OS-specific (only Darwin or only Linux), add the correct `os` value to each config entry in the example so the editor filters it correctly (e.g. `os: ['macOS']`)
 
 **Structure:**
 ```typescript
@@ -401,7 +402,7 @@ import { ExampleConfig } from '@codifycli/plugin-core';
 const defaultConfig: Partial<MyConfig> = {
   someField: 'sensible-default',
   optionalArray: [],
-  // Add os: ['darwin'] or os: ['linux'] if operatingSystems is not [OS.Darwin, OS.Linux]
+  // Add os: ['macOS'] or os: ['linux'] if operatingSystems is not [OS.Darwin, OS.Linux]
 }
 
 const exampleBasic: ExampleConfig = {
@@ -410,7 +411,7 @@ const exampleBasic: ExampleConfig = {
   configs: [{
     type: 'my-resource',
     someField: 'example-value',
-    // Add os: ['darwin'] or os: ['linux'] if the resource is OS-specific
+    // Add os: ['macOS'] or os: ['linux'] if the resource is OS-specific
   }]
 }
 

src/resources/apt/apt.ts

@@ -1,5 +1,5 @@
 import { CreatePlan, ExampleConfig, Resource, ResourceSettings, SpawnStatus, getPty } from '@codifycli/plugin-core';
-import { OS, ResourceConfig, ResourceOs } from '@codifycli/schemas';
+import { LinuxDistro, OS, ResourceConfig, ResourceOs } from '@codifycli/schemas';
 
 import schema from './apt-schema.json';
 import { AptInstallParameter } from './install-parameter.js';
@@ -11,6 +11,7 @@ export interface AptConfig extends ResourceConfig {
 
 const defaultConfig: Partial<AptConfig> = {
   install: [],
+  distro: [LinuxDistro.DEBIAN_BASED],
   os: [ResourceOs.LINUX]
 }
 
@@ -20,6 +21,7 @@ const exampleBasic: ExampleConfig = {
   configs: [{
     type: 'apt',
     os: [ResourceOs.LINUX],
+    distro: [LinuxDistro.DEBIAN_BASED],
     install: ['curl', 'git', 'build-essential'],
   }]
 }
@@ -29,6 +31,7 @@ const exampleVersionPinned: ExampleConfig = {
   description: 'Install packages using apt, with specific versions pinned for reproducibility.',
   configs: [{
     type: 'apt',
+    distro: [LinuxDistro.DEBIAN_BASED],
     os: [ResourceOs.LINUX],
     install: [
       'curl',

src/resources/dnf/dnf.ts

@@ -1,5 +1,5 @@
-import { CreatePlan, Resource, ResourceSettings, SpawnStatus, getPty } from '@codifycli/plugin-core';
-import { OS, ResourceConfig } from '@codifycli/schemas';
+import { CreatePlan, ExampleConfig, getPty, Resource, ResourceSettings, SpawnStatus } from '@codifycli/plugin-core';
+import { LinuxDistro, OS, ResourceConfig, ResourceOs } from '@codifycli/schemas';
 
 import schema from './dnf-schema.json';
 import { DnfInstallParameter, DnfPackage } from './install-parameter.js';
@@ -9,11 +9,47 @@ export interface DnfConfig extends ResourceConfig {
   update?: boolean;
 }
 
+const defaultConfig: Partial<DnfConfig> = {
+  install: [],
+  distro: [LinuxDistro.RPM_BASED],
+  os: [ResourceOs.LINUX]
+}
+
+const exampleBasic: ExampleConfig = {
+  title: 'Install common dev tools with dnf',
+  description: 'Install a set of frequently needed development packages on a Fedora/RHEL-based system.',
+  configs: [{
+    type: 'dnf',
+    install: ['git', 'curl', 'wget', 'vim', 'make'],
+    distro: ['rpm-based'],
+    os: ['linux'],
+  }]
+}
+
+const examplePinned: ExampleConfig = {
+  title: 'Install packages at pinned versions',
+  description: 'Install specific versions of packages to ensure a reproducible development environment across machines.',
+  configs: [{
+    type: 'dnf',
+    install: [
+      { name: 'nodejs', version: '20.0.0' },
+      { name: 'python3', version: '3.11.0' },
+    ],
+    distro: ['rpm-based'],
+    os: ['linux'],
+  }]
+}
+
 export class DnfResource extends Resource<DnfConfig> {
 
   override getSettings(): ResourceSettings<DnfConfig> {
     return {
       id: 'dnf',
+      defaultConfig,
+      exampleConfigs: {
+        example1: exampleBasic,
+        example2: examplePinned,
+      },
       operatingSystems: [OS.Linux],
       schema,
       parameterSettings: {

src/resources/file/file.ts

@@ -1,4 +1,4 @@
-import { CreatePlan, DestroyPlan, ModifyPlan, ParameterChange, Resource, ResourceSettings, z } from '@codifycli/plugin-core';
+import { CreatePlan, DestroyPlan, ExampleConfig, ModifyPlan, ParameterChange, Resource, ResourceSettings, z } from '@codifycli/plugin-core';
 import { OS } from '@codifycli/schemas';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -18,10 +18,41 @@ const schema = z.object({
 
 type FileConfig = z.infer<typeof schema>;
 
+const defaultConfig: Partial<FileConfig> = {
+  path: '<Replace me here!>',
+  contents: '',
+}
+
+const exampleDotfile: ExampleConfig = {
+  title: 'Manage a dotfile with declarative contents',
+  description: 'Create and keep a configuration file in sync with the exact contents specified — useful for dotfiles like .curlrc or .wgetrc.',
+  configs: [{
+    type: 'file',
+    path: '~/.curlrc',
+    contents: '--silent\n--location\n--retry 3\n',
+  }]
+}
+
+const exampleOnlyCreate: ExampleConfig = {
+  title: 'Bootstrap a file only if it does not exist',
+  description: 'Write an initial .env file on first run without overwriting any local edits made afterwards.',
+  configs: [{
+    type: 'file',
+    path: '~/.config/myapp/.env',
+    contents: 'API_URL=https://api.example.com\nDEBUG=false\n',
+    onlyCreate: true,
+  }]
+}
+
 export class FileResource extends Resource<FileConfig> {
   getSettings(): ResourceSettings<FileConfig> {
     return {
       id: 'file',
+      defaultConfig,
+      exampleConfigs: {
+        example1: exampleDotfile,
+        example2: exampleOnlyCreate,
+      },
       operatingSystems: [OS.Darwin, OS.Linux],
       schema,
       parameterSettings: {

src/resources/file/remote-file.ts

@@ -2,6 +2,7 @@ import {
   CodifyCliSender,
   CreatePlan,
   DestroyPlan,
+  ExampleConfig,
   ModifyPlan,
   ParameterChange,
   RefreshContext,
@@ -27,10 +28,41 @@ export interface FileConfig extends ResourceConfig{
   onlyCreate: boolean;
 }
 
+const defaultConfig: Partial<FileConfig> = {
+  path: '<Replace me here!>',
+  remote: '<Replace me here!>',
+}
+
+const exampleSync: ExampleConfig = {
+  title: 'Sync a dotfile from Codify cloud',
+  description: 'Pull a remote file stored in Codify cloud and write it to a local path, keeping it in sync on every apply.',
+  configs: [{
+    type: 'remote-file',
+    path: '~/.zshrc',
+    remote: 'codify://<Replace me here!>:<Replace me here!>',
+  }]
+}
+
+const exampleOnlyCreate: ExampleConfig = {
+  title: 'Bootstrap a config file from Codify cloud without overwriting',
+  description: 'Write the file on first apply only - subsequent applies skip it, so manual local edits are preserved.',
+  configs: [{
+    type: 'remote-file',
+    path: '~/.config/myapp/settings.json',
+    remote: 'codify://<Replace me here!>:<Replace me here!>',
+    onlyCreate: true,
+  }]
+}
+
 export class RemoteFileResource extends Resource<FileConfig> {
   getSettings(): ResourceSettings<FileConfig> {
     return {
       id: 'remote-file',
+      defaultConfig,
+      exampleConfigs: {
+        example1: exampleSync,
+        example2: exampleOnlyCreate,
+      },
       operatingSystems: [OS.Darwin, OS.Linux],
       allowMultiple: true,
       schema,

src/resources/ollama/ollama.ts

@@ -1,5 +1,6 @@
 import {
   CreatePlan,
+  ExampleConfig,
   FileUtils,
   Resource,
   ResourceSettings,
@@ -27,10 +28,37 @@ const schema = z
 
 export type OllamaConfig = z.infer<typeof schema>;
 
+const defaultConfig: Partial<OllamaConfig> = {
+  models: [],
+}
+
+const exampleBasic: ExampleConfig = {
+  title: 'Install Ollama with a model',
+  description: 'Install the Ollama runtime and pull a model to run locally.',
+  configs: [{
+    type: 'ollama',
+    models: ['llama3.2'],
+  }]
+}
+
+const exampleMultiModel: ExampleConfig = {
+  title: 'Install Ollama with multiple models',
+  description: 'Install Ollama and pull several models for local use, including a coding-focused and a general-purpose model.',
+  configs: [{
+    type: 'ollama',
+    models: ['llama3.2', 'mistral', 'qwen2.5-coder'],
+  }]
+}
+
 export class OllamaResource extends Resource<OllamaConfig> {
   getSettings(): ResourceSettings<OllamaConfig> {
     return {
       id: 'ollama',
+      defaultConfig,
+      exampleConfigs: {
+        example1: exampleBasic,
+        example2: exampleMultiModel,
+      },
       operatingSystems: [OS.Darwin, OS.Linux],
       schema,
       dependencies: ['homebrew'],

src/resources/scripting/action.ts

@@ -1,4 +1,4 @@
-import { CreatePlan, DestroyPlan, getPty, Resource, ResourceSettings, SpawnStatus } from '@codifycli/plugin-core';
+import { CreatePlan, DestroyPlan, ExampleConfig, getPty, Resource, ResourceSettings, SpawnStatus } from '@codifycli/plugin-core';
 import { RefreshContext } from '@codifycli/plugin-core/src/resource/resource.js';
 import { OS, StringIndexedObject } from '@codifycli/schemas';
 
@@ -10,11 +10,40 @@ export interface ActionConfig extends StringIndexedObject {
   cwd?: string;
 }
 
+const defaultConfig: Partial<ActionConfig> = {
+  action: '<Replace me here!>',
+}
+
+const exampleConditional: ExampleConfig = {
+  title: 'Run a script only when a condition is met',
+  description: 'Execute a setup command only when the target directory does not already exist, making the action idempotent.',
+  configs: [{
+    type: 'action',
+    condition: '[ ! -d ~/.config/myapp ]',
+    action: 'mkdir -p ~/.config/myapp && cp /etc/myapp/defaults.conf ~/.config/myapp/config.conf',
+  }]
+}
+
+const exampleCwd: ExampleConfig = {
+  title: 'Run a project setup script in a specific directory',
+  description: 'Run a post-clone initialisation script from within a project directory after dependencies are installed.',
+  configs: [{
+    type: 'action',
+    action: 'make bootstrap',
+    cwd: '~/projects/myapp',
+  }]
+}
+
 export class ActionResource extends Resource<ActionConfig> {
-  
+
   getSettings(): ResourceSettings<ActionConfig> {
     return {
       id: 'action',
+      defaultConfig,
+      exampleConfigs: {
+        example1: exampleConditional,
+        example2: exampleCwd,
+      },
       operatingSystems: [OS.Darwin, OS.Linux],
       schema,
       parameterSettings: {