| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Core library for building Codify plugins. Codify is an infrastructure-as-code tool that manages system resources (applications, CLI tools, and settings) through declarative JSON configuration files.
This library provides the foundational abstractions and runtime for creating Codify plugins. Plugins extend Codify's capabilities by implementing resources that can be created, modified, and destroyed on a system. Examples of resources include:
npm install @codifycli/plugin-coreRequirements:
Here's a minimal example of creating a plugin with a single resource:
import { Resource, ResourceSettings, Plugin, runPlugin, getPty } from '@codifycli/plugin-core';
import { StringIndexedObject } from '@codifycli/schemas';
// Define the resource configuration type
interface GitConfig extends StringIndexedObject {
userName?: string;
userEmail?: string;
}
// Implement the Resource abstract class
class GitConfigResource extends Resource<GitConfig> {
getSettings(): ResourceSettings<GitConfig> {
return {
id: 'git-config',
operatingSystems: ['darwin', 'linux'],
schema: {
type: 'object',
properties: {
userName: { type: 'string' },
userEmail: { type: 'string' }
}
}
};
}
async refresh(parameters: Partial<GitConfig>) {
const pty = getPty();
const nameResult = await pty.spawnSafe('git config --global user.name');
const emailResult = await pty.spawnSafe('git config --global user.email');
return {
userName: nameResult.status === 'success' ? nameResult.data.trim() : undefined,
userEmail: emailResult.status === 'success' ? emailResult.data.trim() : undefined
};
}
async create(plan) {
const pty = getPty();
const config = plan.desiredConfig!;
if (config.userName) {
await pty.spawn(`git config --global user.name "${config.userName}"`);
}
if (config.userEmail) {
await pty.spawn(`git config --global user.email "${config.userEmail}"`);
}
}
async destroy(plan) {
const pty = getPty();
await pty.spawn('git config --global --unset user.name');
await pty.spawn('git config --global --unset user.email');
}
}
// Create and run the plugin
const plugin = Plugin.create('my-plugin', [new GitConfigResource()]);
runPlugin(plugin);The top-level container that manages multiple resource types. Handles IPC communication with the Codify CLI.
const plugin = Plugin.create('plugin-name', [
new Resource1(),
new Resource2(),
// ... more resources
]);
runPlugin(plugin);The fundamental building block representing a manageable system entity. Resources must implement:
Represents a set of changes needed to transform the current state into the desired state. Plans contain:
The planning workflow:
Stateless Mode (default):
Stateful Mode:
Parameters with their own lifecycle, tied to the parent resource. Examples:
import { StatefulParameter } from '@codifycli/plugin-core';
class BrewFormulaParameter extends StatefulParameter<BrewConfig, string[]> {
async refresh(desired, config) {
const pty = getPty();
const result = await pty.spawn('brew list --formula');
return result.data.split('\n').filter(Boolean);
}
async add(formulas, plan) {
const pty = getPty();
await pty.spawn(`brew install --formula ${formulas.join(' ')}`);
}
async remove(formulas, plan) {
const pty = getPty();
await pty.spawn(`brew uninstall --formula ${formulas.join(' ')}`);
}
async modify(newValue, previousValue, plan) {
// Handle formula updates
}
}Register in resource settings:
getSettings()
:
ResourceSettings < BrewConfig > {
return {
id: 'homebrew',
parameterSettings: {
formulas: {
type: 'stateful',
implementation: new BrewFormulaParameter()
}
}
};
}Execute shell commands through the PTY abstraction:
import { getPty } from '@codifycli/plugin-core';
const pty = getPty();
// Spawn command (throws on non-zero exit)
const result = await pty.spawn('brew install jq');
// Spawn safely (returns result with status)
const safeResult = await pty.spawnSafe('which jq');
if (safeResult.status === 'success') {
console.log(safeResult.data);
}
// With options
await pty.spawn('npm install', {
cwd: '/path/to/project',
env: { NODE_ENV: 'production' },
interactive: true,
requiresRoot: false
});Two PTY implementations:
Configure resource behavior via ResourceSettings<T>:
getSettings(): ResourceSettings<MyConfig> {
return {
// Required: unique type identifier
id: 'my-resource',
// Required: supported operating systems
operatingSystems: ['darwin', 'linux', 'win32'],
// Optional: supported Linux distributions
linuxDistros: ['ubuntu', 'debian', 'fedora'],
// Schema for validation (JSON Schema or Zod)
schema: {
type: 'object',
properties: {
version: { type: 'string' },
path: { type: 'string' }
},
required: ['version']
},
// Allow multiple instances
allowMultiple: {
identifyingParameters: ['name', 'path'],
matcher: (desired, current) => desired.name === current.name
},
// Prevent resource from being destroyed
canDestroy: false,
// Mark as sensitive (prevents auto-import)
isSensitive: true,
// Resource dependencies
dependencies: ['other-resource-id'],
// Per-parameter settings
parameterSettings: {
path: {
inputTransformation: {
to: (input) => untildify(input), // Expand ~
from: (current) => tildify(current) // Convert to ~
}
},
apiKey: {
isSensitive: true // Hide in plan output
},
tags: {
type: 'array',
isElementEqual: (a, b) => a.name === b.name
}
}
};
}// PTY access
getPty(): IPty
// Path utilities
tildify(absolutePath: string): string
untildify(pathWithTilde: string): string
resolvePathWithVariables(path: string): string
addVariablesToPath(absolutePath: string): string
// File utilities
fileExists(path: string): Promise<boolean>
directoryExists(path: string): Promise<boolean>
// Array utilities
areArraysEqual<T>(a: T[], b: T[], isEqual?: (a: T, b: T) => boolean): booleanThe library includes a codify-build CLI tool for plugin development:
# Generate plugin documentation and validate schemas
npx codify-buildThis tool expects a plugin implementation with a src/resources/ directory structure.
# Install dependencies
npm install
# Run tests
npm test
# Build
npx tsc
# Lint
npx eslint src/See the @codifycli/plugin-core tests for more examples:
ISC
| Back | FazBrowse Home | New Git URL |