Skip to content

The open-source app everyone uses to manage agents at work

Implement markdown-first company package import export

Dotta271c2b9018da
diff --git a/cli/src/commands/client/company.ts b/cli/src/commands/client/company.ts
index b8ab3644f9..ae53864b9c 100644
--- a/cli/src/commands/client/company.ts
+++ b/cli/src/commands/client/company.ts
@@ -1,11 +1,10 @@
import { Command } from "commander";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import type {
Company,
CompanyPortabilityExportResult,
CompanyPortabilityInclude,
- CompanyPortabilityManifest,
CompanyPortabilityPreviewResult,
CompanyPortabilityImportResult,
} from "@paperclipai/shared";
@@ -84,37 +83,39 @@ function isGithubUrl(input: string): boolean {
return /^https?:\/\/github\.com\//i.test(input.trim());
}
+async function collectPackageFiles(root: string, current: string, files: Record<string, string>): Promise<void> {
+ const entries = await readdir(current, { withFileTypes: true });
+ for (const entry of entries) {
+ if (entry.name.startsWith(".git")) continue;
+ const absolutePath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ await collectPackageFiles(root, absolutePath, files);
+ continue;
+ }
+ if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+ const relativePath = path.relative(root, absolutePath).replace(/\\/g, "/");
+ files[relativePath] = await readFile(absolutePath, "utf8");
+ }
+}
+
async function resolveInlineSourceFromPath(inputPath: string): Promise<{
- manifest: CompanyPortabilityManifest;
+ rootPath: string;
files: Record<string, string>;
}> {
const resolved = path.resolve(inputPath);
const resolvedStat = await stat(resolved);
- const manifestPath = resolvedStat.isDirectory()
- ? path.join(resolved, "paperclip.manifest.json")
- : resolved;
- const manifestBaseDir = path.dirname(manifestPath);
- const manifestRaw = await readFile(manifestPath, "utf8");
- const manifest = JSON.parse(manifestRaw) as CompanyPortabilityManifest;
+ const rootDir = resolvedStat.isDirectory() ? resolved : path.dirname(resolved);
const files: Record<string, string> = {};
-
- if (manifest.company?.path) {
- const companyPath = manifest.company.path.replace(/\\/g, "/");
- files[companyPath] = await readFile(path.join(manifestBaseDir, companyPath), "utf8");
- }
- for (const agent of manifest.agents ?? []) {
- const agentPath = agent.path.replace(/\\/g, "/");
- files[agentPath] = await readFile(path.join(manifestBaseDir, agentPath), "utf8");
- }
-
- return { manifest, files };
+ await collectPackageFiles(rootDir, rootDir, files);
+ return {
+ rootPath: path.basename(rootDir),
+ files,
+ };
}
async function writeExportToFolder(outDir: string, exported: CompanyPortabilityExportResult): Promise<void> {
const root = path.resolve(outDir);
await mkdir(root, { recursive: true });
- const manifestPath = path.join(root, "paperclip.manifest.json");
- await writeFile(manifestPath, JSON.stringify(exported.manifest, null, 2), "utf8");
for (const [relativePath, content] of Object.entries(exported.files)) {
const normalized = relativePath.replace(/\\/g, "/");
const filePath = path.join(root, normalized);
@@ -257,7 +258,7 @@ export function registerCompanyCommands(program: Command): void {
addCommonClientOptions(
company
.command("export")
- .description("Export a company into portable manifest + markdown files")
+ .description("Export a company into a portable markdown package")
.argument("<companyId>", "Company ID")
.requiredOption("--out <path>", "Output directory")
.option("--include <values>", "Comma-separated include set: company,agents", "company,agents")
@@ -277,7 +278,8 @@ export function registerCompanyCommands(program: Command): void {
{
ok: true,
out: path.resolve(opts.out!),
- filesWritten: Object.keys(exported.files).length + 1,
+ rootPath: exported.rootPath,
+ filesWritten: Object.keys(exported.files).length,
warningCount: exported.warnings.length,
},
{ json: ctx.json },
@@ -296,7 +298,7 @@ export function registerCompanyCommands(program: Command): void {
addCommonClientOptions(
company
.command("import")
- .description("Import a portable company package from local path, URL, or GitHub")
+ .description("Import a portable markdown company package from local path, URL, or GitHub")
.requiredOption("--from <pathOrUrl>", "Source path or URL")
.option("--include <values>", "Comma-separated include set: company,agents", "company,agents")
.option("--target <mode>", "Target mode: new | existing")
@@ -343,7 +345,7 @@ export function registerCompanyCommands(program: Command): void {
}
let sourcePayload:
- | { type: "inline"; manifest: CompanyPortabilityManifest; files: Record<string, string> }
+ | { type: "inline"; rootPath?: string | null; files: Record<string, string> }
| { type: "url"; url: string }
| { type: "github"; url: string };
@@ -355,7 +357,7 @@ export function registerCompanyCommands(program: Command): void {
const inline = await resolveInlineSourceFromPath(from);
sourcePayload = {
type: "inline",
- manifest: inline.manifest,
+ rootPath: inline.rootPath,
files: inline.files,
};
}
diff --git a/packages/shared/src/types/company-portability.ts b/packages/shared/src/types/company-portability.ts
index 389cd77713..ce6be814f2 100644
--- a/packages/shared/src/types/company-portability.ts
+++ b/packages/shared/src/types/company-portability.ts
@@ -49,6 +49,7 @@ export interface CompanyPortabilityManifest {
}
export interface CompanyPortabilityExportResult {
+ rootPath: string;
manifest: CompanyPortabilityManifest;
files: Record<string, string>;
warnings: string[];
@@ -57,7 +58,7 @@ export interface CompanyPortabilityExportResult {
export type CompanyPortabilitySource =
| {
type: "inline";
- manifest: CompanyPortabilityManifest;
+ rootPath?: string | null;
files: Record<string, string>;
}
| {
diff --git a/packages/shared/src/validators/company-portability.ts b/packages/shared/src/validators/company-portability.ts
index 4ba01a2cdc..7ce3e684f1 100644
--- a/packages/shared/src/validators/company-portability.ts
+++ b/packages/shared/src/validators/company-portability.ts
@@ -60,7 +60,7 @@ export const portabilityManifestSchema = z.object({
export const portabilitySourceSchema = z.discriminatedUnion("type", [
z.object({
type: z.literal("inline"),
- manifest: portabilityManifestSchema,
+ rootPath: z.string().min(1).optional().nullable(),
files: z.record(z.string()),
}),
z.object({
diff --git a/server/src/services/company-portability.ts b/server/src/services/company-portability.ts
index f067e95772..9927dffc9b 100644
--- a/server/src/services/company-portability.ts
+++ b/server/src/services/company-portability.ts
@@ -14,7 +14,7 @@ import type {
CompanyPortabilityPreviewAgentPlan,
CompanyPortabilityPreviewResult,
} from "@paperclipai/shared";
-import { normalizeAgentUrlKey, portabilityManifestSchema } from "@paperclipai/shared";
+import { normalizeAgentUrlKey } from "@paperclipai/shared";
import { notFound, unprocessable } from "../errors.js";
import { accessService } from "./access.js";
import { agentService } from "./agents.js";
@@ -41,6 +41,10 @@ type MarkdownDoc = {
body: string;
};
+type CompanyPackageIncludeEntry = {
+ path: string;
+};
+
type ImportPlanInternal = {
preview: CompanyPortabilityPreviewResult;
source: ResolvedSource;
@@ -146,6 +150,45 @@ function normalizeInclude(input?: Partial<CompanyPortabilityInclude>): CompanyPo
};
}
+function normalizePortablePath(input: string) {
+ const normalized = input.replace(/\\/g, "/").replace(/^\.\/+/, "");
+ const parts: string[] = [];
+ for (const segment of normalized.split("/")) {
+ if (!segment || segment === ".") continue;
+ if (segment === "..") {
+ if (parts.length > 0) parts.pop();
+ continue;
+ }
+ parts.push(segment);
+ }
+ return parts.join("/");
+}
+
+function resolvePortablePath(fromPath: string, targetPath: string) {
+ const baseDir = path.posix.dirname(fromPath.replace(/\\/g, "/"));
+ return normalizePortablePath(path.posix.join(baseDir, targetPath.replace(/\\/g, "/")));
+}
+
+function normalizeFileMap(
+ files: Record<string, string>,
+ rootPath?: string | null,
+): Record<string, string> {
+ const normalizedRoot = rootPath ? normalizePortablePath(rootPath) : null;
+ const out: Record<string, string> = {};
+ for (const [rawPath, content] of Object.entries(files)) {
+ let nextPath = normalizePortablePath(rawPath);
+ if (normalizedRoot && nextPath === normalizedRoot) {
+ continue;
+ }
+ if (normalizedRoot && nextPath.startsWith(`${normalizedRoot}/`)) {
+ nextPath = nextPath.slice(normalizedRoot.length + 1);
+ }
+ if (!nextPath) continue;
+ out[nextPath] = content;
+ }
+ return out;
+}
+
function ensureMarkdownPath(pathValue: string) {
const normalized = pathValue.replace(/\\/g, "/");
if (!normalized.endsWith(".md")) {
@@ -340,6 +383,129 @@ function renderCompanyAgentsSection(agentSummaries: Array<{ slug: string; name:
return lines.join("\n");
}
+function parseYamlScalar(rawValue: string): unknown {
+ const trimmed = rawValue.trim();
+ if (trimmed === "") return "";
+ if (trimmed === "null" || trimmed === "~") return null;
+ if (trimmed === "true") return true;
+ if (trimmed === "false") return false;
+ if (trimmed === "[]") return [];
+ if (trimmed === "{}") return {};
+ if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+ if (
+ trimmed.startsWith("\"") ||
+ trimmed.startsWith("[") ||
+ trimmed.startsWith("{")
+ ) {
+ try {
+ return JSON.parse(trimmed);
+ } catch {
+ return trimmed;
+ }
+ }
+ return trimmed;
+}
+
+function prepareYamlLines(raw: string) {
+ return raw
+ .split("\n")
+ .map((line) => ({
+ indent: line.match(/^ */)?.[0].length ?? 0,
+ content: line.trim(),
+ }))
+ .filter((line) => line.content.length > 0 && !line.content.startsWith("#"));
+}
+
+function parseYamlBlock(
+ lines: Array<{ indent: number; content: string }>,
+ startIndex: number,
+ indentLevel: number,
+): { value: unknown; nextIndex: number } {
+ let index = startIndex;
+ while (index < lines.length && lines[index]!.content.length === 0) {
+ index += 1;
+ }
+ if (index >= lines.length || lines[index]!.indent < indentLevel) {
+ return { value: {}, nextIndex: index };
+ }
+
+ const isArray = lines[index]!.indent === indentLevel && lines[index]!.content.startsWith("-");
+ if (isArray) {
+ const values: unknown[] = [];
+ while (index < lines.length) {
+ const line = lines[index]!;
+ if (line.indent < indentLevel) break;
+ if (line.indent !== indentLevel || !line.content.startsWith("-")) break;
+ const remainder = line.content.slice(1).trim();
+ index += 1;
+ if (!remainder) {
+ const nested = parseYamlBlock(lines, index, indentLevel + 2);
+ values.push(nested.value);
+ index = nested.nextIndex;
+ continue;
+ }
+ const inlineObjectSeparator = remainder.indexOf(":");
+ if (
+ inlineObjectSeparator > 0 &&
+ !remainder.startsWith("\"") &&
+ !remainder.startsWith("{") &&
+ !remainder.startsWith("[")
+ ) {
+ const key = remainder.slice(0, inlineObjectSeparator).trim();
+ const rawValue = remainder.slice(inlineObjectSeparator + 1).trim();
+ const nextObject: Record<string, unknown> = {
+ [key]: parseYamlScalar(rawValue),
+ };
+ if (index < lines.length && lines[index]!.indent > indentLevel) {
+ const nested = parseYamlBlock(lines, index, indentLevel + 2);
+ if (isPlainRecord(nested.value)) {
+ Object.assign(nextObject, nested.value);
+ }
+ index = nested.nextIndex;
+ }
+ values.push(nextObject);
+ continue;
+ }
+ values.push(parseYamlScalar(remainder));
+ }
+ return { value: values, nextIndex: index };
+ }
+
+ const record: Record<string, unknown> = {};
+ while (index < lines.length) {
+ const line = lines[index]!;
+ if (line.indent < indentLevel) break;
+ if (line.indent !== indentLevel) {
+ index += 1;
+ continue;
+ }
+ const separatorIndex = line.content.indexOf(":");
+ if (separatorIndex <= 0) {
+ index += 1;
+ continue;
+ }
+ const key = line.content.slice(0, separatorIndex).trim();
+ const remainder = line.content.slice(separatorIndex + 1).trim();
+ index += 1;
+ if (!remainder) {
+ const nested = parseYamlBlock(lines, index, indentLevel + 2);
+ record[key] = nested.value;
+ index = nested.nextIndex;
+ continue;
+ }
+ record[key] = parseYamlScalar(remainder);
+ }
+
+ return { value: record, nextIndex: index };
+}
+
+function parseYamlFrontmatter(raw: string): Record<string, unknown> {
+ const prepared = prepareYamlLines(raw);
+ if (prepared.length === 0) return {};
+ const parsed = parseYamlBlock(prepared, 0, prepared[0]!.indent);
+ return isPlainRecord(parsed.value) ? parsed.value : {};
+}
+
function parseFrontmatterMarkdown(raw: string): MarkdownDoc {
const normalized = raw.replace(/\r\n/g, "\n");
if (!normalized.startsWith("---\n")) {
@@ -351,45 +517,23 @@ function parseFrontmatterMarkdown(raw: string): MarkdownDoc {
}
const frontmatterRaw = normalized.slice(4, closing).trim();
const body = normalized.slice(closing + 5).trim();
- const frontmatter: Record<string, unknown> = {};
- for (const line of frontmatterRaw.split("\n")) {
- const idx = line.indexOf(":");
- if (idx <= 0) continue;
- const key = line.slice(0, idx).trim();
- const rawValue = line.slice(idx + 1).trim();
- if (!key) continue;
- if (rawValue === "null") {
- frontmatter[key] = null;
- continue;
- }
- if (rawValue === "true" || rawValue === "false") {
- frontmatter[key] = rawValue === "true";
- continue;
- }
- if (/^-?\d+(\.\d+)?$/.test(rawValue)) {
- frontmatter[key] = Number(rawValue);
- continue;
- }
- try {
- frontmatter[key] = JSON.parse(rawValue);
- continue;
- } catch {
- frontmatter[key] = rawValue;
- }
- }
- return { frontmatter, body };
+ return {
+ frontmatter: parseYamlFrontmatter(frontmatterRaw),
+ body,
+ };
}
-async function fetchJson(url: string) {
+async function fetchText(url: string) {
const response = await fetch(url);
if (!response.ok) {
throw unprocessable(`Failed to fetch ${url}: ${response.status}`);
}
- return response.json();
+ return response.text();
}
-async function fetchText(url: string) {
+async function fetchOptionalText(url: string) {
const response = await fetch(url);
+ if (response.status === 404) return null;
if (!response.ok) {
throw unprocessable(`Failed to fetch ${url}: ${response.status}`);
}
@@ -408,7 +552,190 @@ function dedupeRequiredSecrets(values: CompanyPortabilityManifest["requiredSecre
return out;
}
-function parseGitHubTreeUrl(rawUrl: string) {
+function buildIncludes(paths: string[]): CompanyPackageIncludeEntry[] {
+ return paths.map((value) => ({ path: value }));
+}
+
+function readCompanyApprovalDefault(frontmatter: Record<string, unknown>) {
+ const topLevel = frontmatter.requireBoardApprovalForNewAgents;
+ if (typeof topLevel === "boolean") return topLevel;
+ const defaults = frontmatter.defaults;
+ if (isPlainRecord(defaults) && typeof defaults.requireBoardApprovalForNewAgents === "boolean") {
+ return defaults.requireBoardApprovalForNewAgents;
+ }
+ return true;
+}
+
+function readIncludeEntries(frontmatter: Record<string, unknown>): CompanyPackageIncludeEntry[] {
+ const includes = frontmatter.includes;
+ if (!Array.isArray(includes)) return [];
+ return includes.flatMap((entry) => {
+ if (typeof entry === "string") {
+ return [{ path: entry }];
+ }
+ if (isPlainRecord(entry)) {
+ const pathValue = asString(entry.path);
+ return pathValue ? [{ path: pathValue }] : [];
+ }
+ return [];
+ });
+}
+
+function readAgentSecretRequirements(
+ frontmatter: Record<string, unknown>,
+ agentSlug: string,
+): CompanyPortabilityManifest["requiredSecrets"] {
+ const requirements = frontmatter.requirements;
+ const secretsFromRequirements =
+ isPlainRecord(requirements) && Array.isArray(requirements.secrets)
+ ? requirements.secrets
+ : [];
+ const legacyRequiredSecrets = Array.isArray(frontmatter.requiredSecrets)
+ ? frontmatter.requiredSecrets
+ : [];
+ const combined = [...secretsFromRequirements, ...legacyRequiredSecrets];
+
+ return combined.flatMap((entry) => {
+ if (typeof entry === "string" && entry.trim()) {
+ return [{
+ key: entry.trim(),
+ description: `Set ${entry.trim()} for agent ${agentSlug}`,
+ agentSlug,
+ providerHint: null,
+ }];
+ }
+ if (isPlainRecord(entry)) {
+ const key = asString(entry.key);
+ if (!key) return [];
+ return [{
+ key,
+ description: asString(entry.description) ?? `Set ${key} for agent ${agentSlug}`,
+ agentSlug,
+ providerHint: asString(entry.providerHint),
+ }];
+ }
+ return [];
+ });
+}
+
+function buildManifestFromPackageFiles(
+ files: Record<string, string>,
+ opts?: { sourceLabel?: { companyId: string; companyName: string } | null },
+): ResolvedSource {
+ const normalizedFiles = normalizeFileMap(files);
+ const companyPath =
+ normalizedFiles["COMPANY.md"]
+ ?? undefined;
+ const resolvedCompanyPath = companyPath !== undefined
+ ? "COMPANY.md"
+ : Object.keys(normalizedFiles).find((entry) => entry.endsWith("/COMPANY.md") || entry === "COMPANY.md");
+ if (!resolvedCompanyPath) {
+ throw unprocessable("Company package is missing COMPANY.md");
+ }
+
+ const companyDoc = parseFrontmatterMarkdown(normalizedFiles[resolvedCompanyPath]!);
+ const companyFrontmatter = companyDoc.frontmatter;
+ const companyName =
+ asString(companyFrontmatter.name)
+ ?? opts?.sourceLabel?.companyName
+ ?? "Imported Company";
+ const companySlug =
+ asString(companyFrontmatter.slug)
+ ?? normalizeAgentUrlKey(companyName)
+ ?? "company";
+
+ const includeEntries = readIncludeEntries(companyFrontmatter);
+ const referencedAgentPaths = includeEntries
+ .map((entry) => resolvePortablePath(resolvedCompanyPath, entry.path))
+ .filter((entry) => entry.endsWith("/AGENTS.md") || entry === "AGENTS.md");
+ const discoveredAgentPaths = Object.keys(normalizedFiles).filter(
+ (entry) => entry.endsWith("/AGENTS.md") || entry === "AGENTS.md",
+ );
+ const agentPaths = Array.from(new Set([...referencedAgentPaths, ...discoveredAgentPaths])).sort();
+
+ const manifest: CompanyPortabilityManifest = {
+ schemaVersion: 2,
+ generatedAt: new Date().toISOString(),
+ source: opts?.sourceLabel ?? null,
+ includes: {
+ company: true,
+ agents: true,
+ },
+ company: {
+ path: resolvedCompanyPath,
+ name: companyName,
+ description: asString(companyFrontmatter.description),
+ brandColor: asString(companyFrontmatter.brandColor),
+ requireBoardApprovalForNewAgents: readCompanyApprovalDefault(companyFrontmatter),
+ },
+ agents: [],
+ requiredSecrets: [],
+ };
+
+ const warnings: string[] = [];
+ for (const agentPath of agentPaths) {
+ const markdownRaw = normalizedFiles[agentPath];
+ if (typeof markdownRaw !== "string") {
+ warnings.push(`Referenced agent file is missing from package: ${agentPath}`);
+ continue;
+ }
+ const agentDoc = parseFrontmatterMarkdown(markdownRaw);
+ const frontmatter = agentDoc.frontmatter;
+ const fallbackSlug = normalizeAgentUrlKey(path.posix.basename(path.posix.dirname(agentPath))) ?? "agent";
+ const slug = asString(frontmatter.slug) ?? fallbackSlug;
+ const adapter = isPlainRecord(frontmatter.adapter) ? frontmatter.adapter : null;
+ const runtime = isPlainRecord(frontmatter.runtime) ? frontmatter.runtime : null;
+ const permissions = isPlainRecord(frontmatter.permissions) ? frontmatter.permissions : {};
+ const metadata = isPlainRecord(frontmatter.metadata) ? frontmatter.metadata : null;
+ const adapterConfig = isPlainRecord(adapter?.config)
+ ? adapter.config
+ : isPlainRecord(frontmatter.adapterConfig)
+ ? frontmatter.adapterConfig
+ : {};
+ const runtimeConfig = runtime ?? (isPlainRecord(frontmatter.runtimeConfig) ? frontmatter.runtimeConfig : {});
+ const title = asString(frontmatter.title);
+ const capabilities = asString(frontmatter.capabilities);
+
+ manifest.agents.push({
+ slug,
+ name: asString(frontmatter.name) ?? title ?? slug,
+ path: agentPath,
+ role: asString(frontmatter.role) ?? "agent",
+ title,
+ icon: asString(frontmatter.icon),
+ capabilities,
+ reportsToSlug: asString(frontmatter.reportsTo),
+ adapterType: asString(adapter?.type) ?? asString(frontmatter.adapterType) ?? "process",
+ adapterConfig,
+ runtimeConfig,
+ permissions,
+ budgetMonthlyCents:
+ typeof frontmatter.budgetMonthlyCents === "number" && Number.isFinite(frontmatter.budgetMonthlyCents)
+ ? Math.max(0, Math.floor(frontmatter.budgetMonthlyCents))
+ : 0,
+ metadata,
+ });
+
+ manifest.requiredSecrets.push(...readAgentSecretRequirements(frontmatter, slug));
+
+ if (frontmatter.kind !== "agent") {
+ warnings.push(`Agent markdown ${agentPath} does not declare kind: agent in frontmatter.`);
+ }
+ }
+
+ manifest.requiredSecrets = dedupeRequiredSecrets(manifest.requiredSecrets);
+ return {
+ manifest,
+ files: normalizedFiles,
+ warnings,
+ };
+}
+
+function isGitCommitRef(value: string) {
+ return /^[0-9a-f]{40}$/i.test(value.trim());
+}
+
+function parseGitHubSourceUrl(rawUrl: string) {
const url = new URL(rawUrl);
if (url.hostname !== "github.com") {
throw unprocessable("GitHub source must use github.com URL");
@@ -421,11 +748,21 @@ function parseGitHubTreeUrl(rawUrl: string) {
const repo = parts[1]!.replace(/\.git$/i, "");
let ref = "main";
let basePath = "";
+ let companyPath = "COMPANY.md";
if (parts[2] === "tree") {
ref = parts[3] ?? "main";
basePath = parts.slice(4).join("/");
+ } else if (parts[2] === "blob") {
+ ref = parts[3] ?? "main";
+ const blobPath = parts.slice(4).join("/");
+ if (!blobPath) {
+ throw unprocessable("Invalid GitHub blob URL");
+ }
+ companyPath = blobPath;
+ basePath = path.posix.dirname(blobPath);
+ if (basePath === ".") basePath = "";
}
- return { owner, repo, ref, basePath };
+ return { owner, repo, ref, basePath, companyPath };
}
function resolveRawGitHubUrl(owner: string, repo: string, ref: string, filePath: string) {
@@ -485,65 +822,80 @@ export function companyPortabilityService(db: Db) {
async function resolveSource(source: CompanyPortabilityPreview["source"]): Promise<ResolvedSource> {
if (source.type === "inline") {
- return {
- manifest: portabilityManifestSchema.parse(source.manifest),
- files: source.files,
- warnings: [],
- };
+ return buildManifestFromPackageFiles(
+ normalizeFileMap(source.files, source.rootPath),
+ );
}
if (source.type === "url") {
- const manifestJson = await fetchJson(source.url);
- const manifest = portabilityManifestSchema.parse(manifestJson);
- const base = new URL(".", source.url);
- const files: Record<string, string> = {};
- const warnings: string[] = [];
-
- if (manifest.company?.path) {
- const companyPath = ensureMarkdownPath(manifest.company.path);
- files[companyPath] = await fetchText(new URL(companyPath, base).toString());
- }
- for (const agent of manifest.agents) {
- const filePath = ensureMarkdownPath(agent.path);
- files[filePath] = await fetchText(new URL(filePath, base).toString());
+ const normalizedUrl = source.url.trim();
+ const companyUrl = normalizedUrl.endsWith(".md")
+ ? normalizedUrl
+ : new URL("COMPANY.md", normalizedUrl.endsWith("/") ? normalizedUrl : `${normalizedUrl}/`).toString();
+ const companyMarkdown = await fetchText(companyUrl);
+ const files: Record<string, string> = {
+ "COMPANY.md": companyMarkdown,
+ };
+ const companyDoc = parseFrontmatterMarkdown(companyMarkdown);
+ const includeEntries = readIncludeEntries(companyDoc.frontmatter);
+
+ for (const includeEntry of includeEntries) {
+ const includePath = normalizePortablePath(includeEntry.path);
+ if (!includePath.endsWith(".md")) continue;
+ const includeUrl = new URL(includeEntry.path, companyUrl).toString();
+ files[includePath] = await fetchText(includeUrl);
}
-
- return { manifest, files, warnings };
+ return buildManifestFromPackageFiles(files);
}
- const parsed = parseGitHubTreeUrl(source.url);
+ const parsed = parseGitHubSourceUrl(source.url);
let ref = parsed.ref;
- const manifestRelativePath = [parsed.basePath, "paperclip.manifest.json"].filter(Boolean).join("/");
- let manifest: CompanyPortabilityManifest | null = null;
const warnings: string[] = [];
+ if (!isGitCommitRef(ref)) {
+ warnings.push("GitHub source is not pinned to a commit SHA; imports may drift if the ref changes.");
+ }
+ const companyRelativePath = parsed.companyPath === "COMPANY.md"
+ ? [parsed.basePath, "COMPANY.md"].filter(Boolean).join("/")
+ : parsed.companyPath;
+ let companyMarkdown: string | null = null;
try {
- manifest = portabilityManifestSchema.parse(
- await fetchJson(resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, manifestRelativePath)),
+ companyMarkdown = await fetchOptionalText(
+ resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, companyRelativePath),
);
} catch (err) {
if (ref === "main") {
ref = "master";
warnings.push("GitHub ref main not found; falling back to master.");
- manifest = portabilityManifestSchema.parse(
- await fetchJson(resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, manifestRelativePath)),
+ companyMarkdown = await fetchOptionalText(
+ resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, companyRelativePath),
);
} else {
throw err;
}
}
-
- const files: Record<string, string> = {};
- if (manifest.company?.path) {
- files[manifest.company.path] = await fetchText(
- resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, [parsed.basePath, manifest.company.path].filter(Boolean).join("/")),
- );
+ if (!companyMarkdown) {
+ throw unprocessable("GitHub company package is missing COMPANY.md");
}
- for (const agent of manifest.agents) {
- files[agent.path] = await fetchText(
- resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, [parsed.basePath, agent.path].filter(Boolean).join("/")),
+
+ const companyPath = parsed.companyPath === "COMPANY.md"
+ ? "COMPANY.md"
+ : normalizePortablePath(path.posix.relative(parsed.basePath || ".", parsed.companyPath));
+ const files: Record<string, string> = {
+ [companyPath]: companyMarkdown,
+ };
+ const companyDoc = parseFrontmatterMarkdown(companyMarkdown);
+ const includeEntries = readIncludeEntries(companyDoc.frontmatter);
+ for (const includeEntry of includeEntries) {
+ const repoPath = [parsed.basePath, includeEntry.path].filter(Boolean).join("/");
+ if (!repoPath.endsWith(".md")) continue;
+ files[normalizePortablePath(includeEntry.path)] = await fetchText(
+ resolveRawGitHubUrl(parsed.owner, parsed.repo, ref, repoPath),
);
}
- return { manifest, files, warnings };
+
+ const resolved = buildManifestFromPackageFiles(files);
+ resolved.warnings.unshift(...warnings);
+ return resolved;
}
async function exportBundle(
@@ -557,20 +909,7 @@ export function companyPortabilityService(db: Db) {
const files: Record<string, string> = {};
const warnings: string[] = [];
const requiredSecrets: CompanyPortabilityManifest["requiredSecrets"] = [];
- const generatedAt = new Date().toISOString();
-
- const manifest: CompanyPortabilityManifest = {
- schemaVersion: 1,
- generatedAt,
- source: {
- companyId: company.id,
- companyName: company.name,
- },
- includes: include,
- company: null,
- agents: [],
- requiredSecrets: [],
- };
+ const rootPath = normalizeAgentUrlKey(company.name) ?? "company-package";
const allAgentRows = include.agents ? await agents.list(companyId, { includeTerminated: true }) : [];
const agentRows = allAgentRows.filter((agent) => agent.status !== "terminated");
@@ -589,29 +928,32 @@ export function companyPortabilityService(db: Db) {
idToSlug.set(agent.id, slug);
}
- if (include.company) {
+ {
const companyPath = "COMPANY.md";
const companyAgentSummaries = agentRows.map((agent) => ({
slug: idToSlug.get(agent.id) ?? "agent",
name: agent.name,
}));
+ const includes = include.agents
+ ? buildIncludes(
+ companyAgentSummaries.map((agent) => `agents/${agent.slug}/AGENTS.md`),
+ )
+ : [];
files[companyPath] = buildMarkdown(
{
+ schema: "company-packages/v0.1",
kind: "company",
+ slug: rootPath,
name: company.name,
description: company.description ?? null,
brandColor: company.brandColor ?? null,
- requireBoardApprovalForNewAgents: company.requireBoardApprovalForNewAgents,
+ defaults: {
+ requireBoardApprovalForNewAgents: company.requireBoardApprovalForNewAgents,
+ },
+ includes,
},
renderCompanyAgentsSection(companyAgentSummaries),
);
- manifest.company = {
- path: companyPath,
- name: company.name,
- description: company.description ?? null,
- brandColor: company.brandColor ?? null,
- requireBoardApprovalForNewAgents: company.requireBoardApprovalForNewAgents,
- };
}
if (include.agents) {
@@ -647,46 +989,52 @@ export function companyPortabilityService(db: Db) {
files[agentPath] = buildMarkdown(
{
+ schema: "company-packages/v0.1",
name: agent.name,
slug,
- role: agent.role,
- adapterType: agent.adapterType,
kind: "agent",
+ role: agent.role,
+ title: agent.title ?? null,
icon: agent.icon ?? null,
capabilities: agent.capabilities ?? null,
reportsTo: reportsToSlug,
- runtimeConfig: portableRuntimeConfig,
+ adapter: {
+ type: agent.adapterType,
+ config: portableAdapterConfig,
+ },
+ runtime: portableRuntimeConfig,
permissions: portablePermissions,
- adapterConfig: portableAdapterConfig,
- requiredSecrets: agentRequiredSecrets,
+ budgetMonthlyCents: agent.budgetMonthlyCents ?? 0,
+ metadata: (agent.metadata as Record<string, unknown> | null) ?? null,
+ requirements: agentRequiredSecrets.length > 0
+ ? {
+ secrets: agentRequiredSecrets.map((secret) => ({
+ key: secret.key,
+ description: secret.description,
+ providerHint: secret.providerHint,
+ })),
+ }
+ : {},
},
instructions.body,
);
-
- manifest.agents.push({
- slug,
- name: agent.name,
- path: agentPath,
- role: agent.role,
- title: agent.title ?? null,
- icon: agent.icon ?? null,
- capabilities: agent.capabilities ?? null,
- reportsToSlug,
- adapterType: agent.adapterType,
- adapterConfig: portableAdapterConfig,
- runtimeConfig: portableRuntimeConfig,
- permissions: portablePermissions,
- budgetMonthlyCents: agent.budgetMonthlyCents ?? 0,
- metadata: (agent.metadata as Record<string, unknown> | null) ?? null,
- });
}
}
- manifest.requiredSecrets = dedupeRequiredSecrets(requiredSecrets);
+ const resolved = buildManifestFromPackageFiles(files, {
+ sourceLabel: {
+ companyId: company.id,
+ companyName: company.name,
+ },
+ });
+ resolved.manifest.includes = include;
+ resolved.manifest.requiredSecrets = dedupeRequiredSecrets(requiredSecrets);
+ resolved.warnings.unshift(...warnings);
return {
- manifest,
+ rootPath,
+ manifest: resolved.manifest,
files,
- warnings,
+ warnings: resolved.warnings,
};
}
@@ -702,11 +1050,17 @@ export function companyPortabilityService(db: Db) {
errors.push("Manifest does not include company metadata.");
}
- const selectedSlugs = input.agents && input.agents !== "all"
- ? Array.from(new Set(input.agents))
- : manifest.agents.map((agent) => agent.slug);
-
- const selectedAgents = manifest.agents.filter((agent) => selectedSlugs.includes(agent.slug));
+ const selectedSlugs = include.agents
+ ? (
+ input.agents && input.agents !== "all"
+ ? Array.from(new Set(input.agents))
+ : manifest.agents.map((agent) => agent.slug)
+ )
+ : [];
+
+ const selectedAgents = include.agents
+ ? manifest.agents.filter((agent) => selectedSlugs.includes(agent.slug))
+ : [];
const selectedMissing = selectedSlugs.filter((slug) => !manifest.agents.some((agent) => agent.slug === slug));
for (const missing of selectedMissing) {
errors.push(`Selected agent slug not found in manifest: ${missing}`);
diff --git a/ui/src/pages/CompanySettings.tsx b/ui/src/pages/CompanySettings.tsx
index 95ba1d7500..13c5598981 100644
--- a/ui/src/pages/CompanySettings.tsx
+++ b/ui/src/pages/CompanySettings.tsx
@@ -1,12 +1,20 @@
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useRef, useState, type ChangeEvent } from "react";
import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type {
+ CompanyPortabilityCollisionStrategy,
+ CompanyPortabilityExportResult,
+ CompanyPortabilityPreviewRequest,
+ CompanyPortabilityPreviewResult,
+ CompanyPortabilitySource,
+} from "@paperclipai/shared";
import { useCompany } from "../context/CompanyContext";
import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useToast } from "../context/ToastContext";
import { companiesApi } from "../api/companies";
import { accessApi } from "../api/access";
import { queryKeys } from "../lib/queryKeys";
import { Button } from "@/components/ui/button";
-import { Settings, Check } from "lucide-react";
+import { Settings, Check, Download, Github, Link2, Upload } from "lucide-react";
import { CompanyPatternIcon } from "../components/CompanyPatternIcon";
import {
Field,
@@ -28,7 +36,9 @@ export function CompanySettings() {
setSelectedCompanyId
} = useCompany();
const { setBreadcrumbs } = useBreadcrumbs();
+ const { pushToast } = useToast();
const queryClient = useQueryClient();
+ const packageInputRef = useRef<HTMLInputElement | null>(null);
// General settings local state
const [companyName, setCompanyName] = useState("");
@@ -47,6 +57,18 @@ export function CompanySettings() {
const [inviteSnippet, setInviteSnippet] = useState<string | null>(null);
const [snippetCopied, setSnippetCopied] = useState(false);
const [snippetCopyDelightId, setSnippetCopyDelightId] = useState(0);
+ const [packageIncludeCompany, setPackageIncludeCompany] = useState(true);
+ const [packageIncludeAgents, setPackageIncludeAgents] = useState(true);
+ const [importSourceMode, setImportSourceMode] = useState<"github" | "url" | "local">("github");
+ const [importUrl, setImportUrl] = useState("");
+ const [importTargetMode, setImportTargetMode] = useState<"existing" | "new">("existing");
+ const [newCompanyName, setNewCompanyName] = useState("");
+ const [collisionStrategy, setCollisionStrategy] = useState<CompanyPortabilityCollisionStrategy>("rename");
+ const [localPackage, setLocalPackage] = useState<{
+ rootPath: string | null;
+ files: Record<string, string>;
+ } | null>(null);
+ const [importPreview, setImportPreview] = useState<CompanyPortabilityPreviewResult | null>(null);
const generalDirty =
!!selectedCompany &&
@@ -54,6 +76,57 @@ export function CompanySettings() {
description !== (selectedCompany.description ?? "") ||
brandColor !== (selectedCompany.brandColor ?? ""));
+ const packageInclude = useMemo(
+ () => ({
+ company: packageIncludeCompany,
+ agents: packageIncludeAgents
+ }),
+ [packageIncludeAgents, packageIncludeCompany]
+ );
+
+ const importSource = useMemo<CompanyPortabilitySource | null>(() => {
+ if (importSourceMode === "local") {
+ if (!localPackage || Object.keys(localPackage.files).length === 0) return null;
+ return {
+ type: "inline",
+ rootPath: localPackage.rootPath,
+ files: localPackage.files
+ };
+ }
+ const trimmed = importUrl.trim();
+ if (!trimmed) return null;
+ return importSourceMode === "github"
+ ? { type: "github", url: trimmed }
+ : { type: "url", url: trimmed };
+ }, [importSourceMode, importUrl, localPackage]);
+
+ const importPayload = useMemo<CompanyPortabilityPreviewRequest | null>(() => {
+ if (!importSource) return null;
+ return {
+ source: importSource,
+ include: packageInclude,
+ target:
+ importTargetMode === "new"
+ ? {
+ mode: "new_company",
+ newCompanyName: newCompanyName.trim() || null
+ }
+ : {
+ mode: "existing_company",
+ companyId: selectedCompanyId!
+ },
+ agents: "all",
+ collisionStrategy
+ };
+ }, [
+ collisionStrategy,
+ importSource,
+ importTargetMode,
+ newCompanyName,
+ packageInclude,
+ selectedCompanyId
+ ]);
+
const generalMutation = useMutation({
mutationFn: (data: {
name: string;
@@ -75,6 +148,102 @@ export function CompanySettings() {
}
});
+ const exportMutation = useMutation({
+ mutationFn: () =>
+ companiesApi.exportBundle(selectedCompanyId!, {
+ include: packageInclude
+ }),
+ onSuccess: async (exported) => {
+ await downloadCompanyPackage(exported);
+ pushToast({
+ tone: "success",
+ title: "Company package exported",
+ body: `${exported.rootPath}.tar downloaded with ${Object.keys(exported.files).length} file${Object.keys(exported.files).length === 1 ? "" : "s"}.`
+ });
+ if (exported.warnings.length > 0) {
+ pushToast({
+ tone: "warn",
+ title: "Export completed with warnings",
+ body: exported.warnings[0]
+ });
+ }
+ },
+ onError: (err) => {
+ pushToast({
+ tone: "error",
+ title: "Export failed",
+ body: err instanceof Error ? err.message : "Failed to export company package"
+ });
+ }
+ });
+
+ const previewImportMutation = useMutation({
+ mutationFn: (payload: CompanyPortabilityPreviewRequest) =>
+ companiesApi.importPreview(payload),
+ onSuccess: (preview) => {
+ setImportPreview(preview);
+ if (preview.errors.length > 0) {
+ pushToast({
+ tone: "warn",
+ title: "Import preview found issues",
+ body: preview.errors[0]
+ });
+ return;
+ }
+ pushToast({
+ tone: "success",
+ title: "Import preview ready",
+ body: `${preview.plan.agentPlans.length} agent action${preview.plan.agentPlans.length === 1 ? "" : "s"} planned.`
+ });
+ },
+ onError: (err) => {
+ setImportPreview(null);
+ pushToast({
+ tone: "error",
+ title: "Import preview failed",
+ body: err instanceof Error ? err.message : "Failed to preview company package"
+ });
+ }
+ });
+
+ const importPackageMutation = useMutation({
+ mutationFn: (payload: CompanyPortabilityPreviewRequest) =>
+ companiesApi.importBundle(payload),
+ onSuccess: async (result) => {
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.companies.all }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.companies.stats }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(result.company.id) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.org(result.company.id) })
+ ]);
+ if (importTargetMode === "new") {
+ setSelectedCompanyId(result.company.id);
+ }
+ pushToast({
+ tone: "success",
+ title: "Company package imported",
+ body: `${result.agents.filter((agent) => agent.action !== "skipped").length} agent${result.agents.filter((agent) => agent.action !== "skipped").length === 1 ? "" : "s"} applied.`
+ });
+ if (result.warnings.length > 0) {
+ pushToast({
+ tone: "warn",
+ title: "Import completed with warnings",
+ body: result.warnings[0]
+ });
+ }
+ setImportPreview(null);
+ setLocalPackage(null);
+ setImportUrl("");
+ },
+ onError: (err) => {
+ pushToast({
+ tone: "error",
+ title: "Import failed",
+ body: err instanceof Error ? err.message : "Failed to import company package"
+ });
+ }
+ });
+
const inviteMutation = useMutation({
mutationFn: () =>
accessApi.createOpenClawInvitePrompt(selectedCompanyId!),
@@ -134,6 +303,21 @@ export function CompanySettings() {
setSnippetCopied(false);
setSnippetCopyDelightId(0);
}, [selectedCompanyId]);
+
+ useEffect(() => {
+ setImportPreview(null);
+ }, [
+ collisionStrategy,
+ importSourceMode,
+ importTargetMode,
+ importUrl,
+ localPackage,
+ newCompanyName,
+ packageIncludeAgents,
+ packageIncludeCompany,
+ selectedCompanyId
+ ]);
+
const archiveMutation = useMutation({
mutationFn: ({
companyId,
@@ -178,6 +362,64 @@ export function CompanySettings() {
});
}
+ async function handleChooseLocalPackage(
+ event: ChangeEvent<HTMLInputElement>
+ ) {
+ const selection = event.target.files;
+ if (!selection || selection.length === 0) {
+ setLocalPackage(null);
+ return;
+ }
+ try {
+ const parsed = await readLocalPackageSelection(selection);
+ setLocalPackage(parsed);
+ pushToast({
+ tone: "success",
+ title: "Local package loaded",
+ body: `${Object.keys(parsed.files).length} markdown file${Object.keys(parsed.files).length === 1 ? "" : "s"} ready for preview.`
+ });
+ } catch (err) {
+ setLocalPackage(null);
+ pushToast({
+ tone: "error",
+ title: "Failed to read local package",
+ body: err instanceof Error ? err.message : "Could not read selected files"
+ });
+ } finally {
+ event.target.value = "";
+ }
+ }
+
+ function handlePreviewImport() {
+ if (!importPayload) {
+ pushToast({
+ tone: "warn",
+ title: "Source required",
+ body:
+ importSourceMode === "local"
+ ? "Choose a local folder with COMPANY.md before previewing."
+ : "Enter a company package URL before previewing."
+ });
+ return;
+ }
+ previewImportMutation.mutate(importPayload);
+ }
+
+ function handleApplyImport() {
+ if (!importPayload) {
+ pushToast({
+ tone: "warn",
+ title: "Source required",
+ body:
+ importSourceMode === "local"
+ ? "Choose a local folder with COMPANY.md before importing."
+ : "Enter a company package URL before importing."
+ });
+ return;
+ }
+ importPackageMutation.mutate(importPayload);
+ }
+
return (
<div className="max-w-2xl space-y-6">
<div className="flex items-center gap-2">
@@ -379,6 +621,355 @@ export function CompanySettings() {
</div>
</div>
+ {/* Import / Export */}
+ <div className="space-y-4">
+ <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+ Company Packages
+ </div>
+
+ <div className="space-y-4 rounded-md border border-border px-4 py-4">
+ <div className="flex items-start justify-between gap-4">
+ <div className="space-y-1">
+ <div className="text-sm font-medium">Export markdown package</div>
+ <p className="text-xs text-muted-foreground">
+ Download a markdown-first company package as a single tar file.
+ </p>
+ </div>
+ <Button
+ size="sm"
+ onClick={() => exportMutation.mutate()}
+ disabled={
+ exportMutation.isPending ||
+ (!packageIncludeCompany && !packageIncludeAgents)
+ }
+ >
+ <Download className="mr-1 h-3.5 w-3.5" />
+ {exportMutation.isPending ? "Exporting..." : "Export package"}
+ </Button>
+ </div>
+
+ <div className="grid gap-3 md:grid-cols-2">
+ <label className="flex items-center gap-2 rounded-md border border-border px-3 py-2 text-sm">
+ <input
+ type="checkbox"
+ checked={packageIncludeCompany}
+ onChange={(e) => setPackageIncludeCompany(e.target.checked)}
+ />
+ Include company metadata
+ </label>
+ <label className="flex items-center gap-2 rounded-md border border-border px-3 py-2 text-sm">
+ <input
+ type="checkbox"
+ checked={packageIncludeAgents}
+ onChange={(e) => setPackageIncludeAgents(e.target.checked)}
+ />
+ Include agents
+ </label>
+ </div>
+
+ {exportMutation.data && (
+ <div className="rounded-md border border-border bg-muted/20 p-3">
+ <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ Last export
+ </div>
+ <div className="mt-2 text-sm">
+ {exportMutation.data.rootPath}.tar with{" "}
+ {Object.keys(exportMutation.data.files).length} file
+ {Object.keys(exportMutation.data.files).length === 1 ? "" : "s"}.
+ </div>
+ <div className="mt-2 flex flex-wrap gap-2 text-xs text-muted-foreground">
+ {Object.keys(exportMutation.data.files).map((filePath) => (
+ <span
+ key={filePath}
+ className="rounded-full border border-border px-2 py-0.5"
+ >
+ {filePath}
+ </span>
+ ))}
+ </div>
+ {exportMutation.data.warnings.length > 0 && (
+ <div className="mt-3 space-y-1 text-xs text-amber-700">
+ {exportMutation.data.warnings.map((warning) => (
+ <div key={warning}>{warning}</div>
+ ))}
+ </div>
+ )}
+ </div>
+ )}
+ </div>
+
+ <div className="space-y-4 rounded-md border border-border px-4 py-4">
+ <div className="space-y-1">
+ <div className="text-sm font-medium">Import company package</div>
+ <p className="text-xs text-muted-foreground">
+ Preview a GitHub repo, direct COMPANY.md URL, or local folder before applying it.
+ </p>
+ </div>
+
+ <div className="grid gap-2 md:grid-cols-3">
+ <button
+ type="button"
+ className={`rounded-md border px-3 py-2 text-left text-sm transition-colors ${
+ importSourceMode === "github"
+ ? "border-foreground bg-accent"
+ : "border-border hover:bg-accent/50"
+ }`}
+ onClick={() => setImportSourceMode("github")}
+ >
+ <div className="flex items-center gap-2">
+ <Github className="h-4 w-4" />
+ GitHub repo
+ </div>
+ </button>
+ <button
+ type="button"
+ className={`rounded-md border px-3 py-2 text-left text-sm transition-colors ${
+ importSourceMode === "url"
+ ? "border-foreground bg-accent"
+ : "border-border hover:bg-accent/50"
+ }`}
+ onClick={() => setImportSourceMode("url")}
+ >
+ <div className="flex items-center gap-2">
+ <Link2 className="h-4 w-4" />
+ Direct URL
+ </div>
+ </button>
+ <button
+ type="button"
+ className={`rounded-md border px-3 py-2 text-left text-sm transition-colors ${
+ importSourceMode === "local"
+ ? "border-foreground bg-accent"
+ : "border-border hover:bg-accent/50"
+ }`}
+ onClick={() => setImportSourceMode("local")}
+ >
+ <div className="flex items-center gap-2">
+ <Upload className="h-4 w-4" />
+ Local folder
+ </div>
+ </button>
+ </div>
+
+ {importSourceMode === "local" ? (
+ <div className="rounded-md border border-dashed border-border px-3 py-3">
+ <input
+ ref={packageInputRef}
+ type="file"
+ multiple
+ className="hidden"
+ // @ts-expect-error webkitdirectory is supported by Chromium-based browsers
+ webkitdirectory=""
+ onChange={handleChooseLocalPackage}
+ />
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="sm"
+ variant="outline"
+ onClick={() => packageInputRef.current?.click()}
+ >
+ Choose folder
+ </Button>
+ {localPackage && (
+ <span className="text-xs text-muted-foreground">
+ {localPackage.rootPath ?? "package"} with{" "}
+ {Object.keys(localPackage.files).length} markdown file
+ {Object.keys(localPackage.files).length === 1 ? "" : "s"}
+ </span>
+ )}
+ </div>
+ {!localPackage && (
+ <p className="mt-2 text-xs text-muted-foreground">
+ Select a folder that contains COMPANY.md and any referenced
+ AGENTS.md files.
+ </p>
+ )}
+ </div>
+ ) : (
+ <Field
+ label={importSourceMode === "github" ? "GitHub URL" : "Package URL"}
+ hint={
+ importSourceMode === "github"
+ ? "Repo root, tree path, or blob URL to COMPANY.md. Unpinned refs warn but do not block."
+ : "Point directly at COMPANY.md or a directory that contains it."
+ }
+ >
+ <input
+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+ type="text"
+ value={importUrl}
+ placeholder={
+ importSourceMode === "github"
+ ? "https://github.com/owner/repo/tree/main/company"
+ : "https://example.com/company/COMPANY.md"
+ }
+ onChange={(e) => setImportUrl(e.target.value)}
+ />
+ </Field>
+ )}
+
+ <div className="grid gap-3 md:grid-cols-2">
+ <Field
+ label="Target"
+ hint="Import into this company or create a new one from the package."
+ >
+ <select
+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+ value={importTargetMode}
+ onChange={(e) =>
+ setImportTargetMode(e.target.value as "existing" | "new")
+ }
+ >
+ <option value="existing">
+ Existing company: {selectedCompany.name}
+ </option>
+ <option value="new">Create new company</option>
+ </select>
+ </Field>
+ <Field
+ label="Collision strategy"
+ hint="Controls what happens when imported agent slugs already exist."
+ >
+ <select
+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+ value={collisionStrategy}
+ onChange={(e) =>
+ setCollisionStrategy(
+ e.target.value as CompanyPortabilityCollisionStrategy
+ )
+ }
+ >
+ <option value="rename">Rename imported agents</option>
+ <option value="skip">Skip existing agents</option>
+ <option value="replace">Replace existing agents</option>
+ </select>
+ </Field>
+ </div>
+
+ {importTargetMode === "new" && (
+ <Field
+ label="New company name"
+ hint="Optional override. Leave blank to use the package name."
+ >
+ <input
+ className="w-full rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm outline-none"
+ type="text"
+ value={newCompanyName}
+ onChange={(e) => setNewCompanyName(e.target.value)}
+ placeholder="Imported Company"
+ />
+ </Field>
+ )}
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="sm"
+ variant="outline"
+ onClick={handlePreviewImport}
+ disabled={
+ previewImportMutation.isPending ||
+ (!packageIncludeCompany && !packageIncludeAgents)
+ }
+ >
+ {previewImportMutation.isPending ? "Previewing..." : "Preview import"}
+ </Button>
+ <Button
+ size="sm"
+ onClick={handleApplyImport}
+ disabled={
+ importPackageMutation.isPending ||
+ previewImportMutation.isPending ||
+ !!(importPreview && importPreview.errors.length > 0) ||
+ (!packageIncludeCompany && !packageIncludeAgents)
+ }
+ >
+ {importPackageMutation.isPending ? "Importing..." : "Apply import"}
+ </Button>
+ </div>
+
+ {importPreview && (
+ <div className="space-y-3 rounded-md border border-border bg-muted/20 p-3">
+ <div className="grid gap-2 md:grid-cols-2">
+ <div className="rounded-md border border-border bg-background/70 px-3 py-2">
+ <div className="text-xs uppercase tracking-wide text-muted-foreground">
+ Company action
+ </div>
+ <div className="mt-1 text-sm font-medium">
+ {importPreview.plan.companyAction}
+ </div>
+ </div>
+ <div className="rounded-md border border-border bg-background/70 px-3 py-2">
+ <div className="text-xs uppercase tracking-wide text-muted-foreground">
+ Agent actions
+ </div>
+ <div className="mt-1 text-sm font-medium">
+ {importPreview.plan.agentPlans.length}
+ </div>
+ </div>
+ </div>
+
+ {importPreview.plan.agentPlans.length > 0 && (
+ <div className="space-y-2">
+ {importPreview.plan.agentPlans.map((agentPlan) => (
+ <div
+ key={agentPlan.slug}
+ className="rounded-md border border-border bg-background/70 px-3 py-2"
+ >
+ <div className="flex items-center justify-between gap-2 text-sm">
+ <span className="font-medium">
+ {agentPlan.slug} {"->"} {agentPlan.plannedName}
+ </span>
+ <span className="rounded-full border border-border px-2 py-0.5 text-xs uppercase tracking-wide text-muted-foreground">
+ {agentPlan.action}
+ </span>
+ </div>
+ {agentPlan.reason && (
+ <div className="mt-1 text-xs text-muted-foreground">
+ {agentPlan.reason}
+ </div>
+ )}
+ </div>
+ ))}
+ </div>
+ )}
+
+ {importPreview.requiredSecrets.length > 0 && (
+ <div className="space-y-1">
+ <div className="text-xs uppercase tracking-wide text-muted-foreground">
+ Required secrets
+ </div>
+ {importPreview.requiredSecrets.map((secret) => (
+ <div
+ key={`${secret.agentSlug ?? "company"}:${secret.key}`}
+ className="text-xs text-muted-foreground"
+ >
+ {secret.key}
+ {secret.agentSlug ? ` for ${secret.agentSlug}` : ""}
+ </div>
+ ))}
+ </div>
+ )}
+
+ {importPreview.warnings.length > 0 && (
+ <div className="space-y-1 rounded-md border border-amber-300/60 bg-amber-50/60 px-3 py-2 text-xs text-amber-700">
+ {importPreview.warnings.map((warning) => (
+ <div key={warning}>{warning}</div>
+ ))}
+ </div>
+ )}
+
+ {importPreview.errors.length > 0 && (
+ <div className="space-y-1 rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-xs text-destructive">
+ {importPreview.errors.map((error) => (
+ <div key={error}>{error}</div>
+ ))}
+ </div>
+ )}
+ </div>
+ )}
+ </div>
+ </div>
+
{/* Danger Zone */}
<div className="space-y-4">
<div className="text-xs font-medium text-destructive uppercase tracking-wide">
@@ -435,6 +1026,131 @@ export function CompanySettings() {
);
}
+async function readLocalPackageSelection(fileList: FileList): Promise<{
+ rootPath: string | null;
+ files: Record<string, string>;
+}> {
+ const files: Record<string, string> = {};
+ let rootPath: string | null = null;
+
+ for (const file of Array.from(fileList)) {
+ const relativePath =
+ (file as File & { webkitRelativePath?: string }).webkitRelativePath?.replace(
+ /\\/g,
+ "/"
+ ) || file.name;
+ if (!relativePath.endsWith(".md")) continue;
+ const topLevel = relativePath.split("/")[0] ?? null;
+ if (!rootPath && topLevel) rootPath = topLevel;
+ files[relativePath] = await file.text();
+ }
+
+ if (Object.keys(files).length === 0) {
+ throw new Error("No markdown files were found in the selected folder.");
+ }
+
+ return { rootPath, files };
+}
+
+async function downloadCompanyPackage(
+ exported: CompanyPortabilityExportResult
+): Promise<void> {
+ const tarBytes = createTarArchive(exported.files, exported.rootPath);
+ const tarBuffer = new ArrayBuffer(tarBytes.byteLength);
+ new Uint8Array(tarBuffer).set(tarBytes);
+ const blob = new Blob(
+ [tarBuffer],
+ {
+ type: "application/x-tar"
+ }
+ );
+ const url = URL.createObjectURL(blob);
+ const anchor = document.createElement("a");
+ anchor.href = url;
+ anchor.download = `${exported.rootPath}.tar`;
+ document.body.appendChild(anchor);
+ anchor.click();
+ anchor.remove();
+ window.setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+function createTarArchive(
+ files: Record<string, string>,
+ rootPath: string
+): Uint8Array {
+ const encoder = new TextEncoder();
+ const chunks: Uint8Array[] = [];
+
+ for (const [relativePath, contents] of Object.entries(files)) {
+ const tarPath = `${rootPath}/${relativePath}`.replace(/\\/g, "/");
+ const body = encoder.encode(contents);
+ chunks.push(buildTarHeader(tarPath, body.length));
+ chunks.push(body);
+ const remainder = body.length % 512;
+ if (remainder > 0) {
+ chunks.push(new Uint8Array(512 - remainder));
+ }
+ }
+
+ chunks.push(new Uint8Array(1024));
+
+ const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+ const archive = new Uint8Array(totalLength);
+ let offset = 0;
+ for (const chunk of chunks) {
+ archive.set(chunk, offset);
+ offset += chunk.length;
+ }
+ return archive;
+}
+
+function buildTarHeader(pathname: string, size: number): Uint8Array {
+ const header = new Uint8Array(512);
+ writeTarString(header, 0, 100, pathname);
+ writeTarOctal(header, 100, 8, 0o644);
+ writeTarOctal(header, 108, 8, 0);
+ writeTarOctal(header, 116, 8, 0);
+ writeTarOctal(header, 124, 12, size);
+ writeTarOctal(header, 136, 12, Math.floor(Date.now() / 1000));
+ for (let i = 148; i < 156; i += 1) {
+ header[i] = 32;
+ }
+ header[156] = "0".charCodeAt(0);
+ writeTarString(header, 257, 6, "ustar");
+ writeTarString(header, 263, 2, "00");
+ const checksum = header.reduce((sum, byte) => sum + byte, 0);
+ writeTarChecksum(header, checksum);
+ return header;
+}
+
+function writeTarString(
+ target: Uint8Array,
+ offset: number,
+ length: number,
+ value: string
+) {
+ const encoded = new TextEncoder().encode(value);
+ target.set(encoded.slice(0, length), offset);
+}
+
+function writeTarOctal(
+ target: Uint8Array,
+ offset: number,
+ length: number,
+ value: number
+) {
+ const stringValue = value.toString(8).padStart(length - 1, "0");
+ writeTarString(target, offset, length - 1, stringValue);
+ target[offset + length - 1] = 0;
+}
+
+function writeTarChecksum(target: Uint8Array, checksum: number) {
+ const stringValue = checksum.toString(8).padStart(6, "0");
+ writeTarString(target, 148, 6, stringValue);
+ target[154] = 0;
+ target[155] = 32;
+}
+
function buildAgentSnippet(input: AgentSnippetInput) {
const candidateUrls = buildCandidateOnboardingUrls(input);
const resolutionTestUrl = buildResolutionTestUrl(input);