@jakubmazanec/carson 0.1.0-11dd4a3

package/src/commands/update-workspace/UpdateWorkspace.tsx

@@ -0,0 +1,59 @@
+import {type CommandArguments, Header, icons, colors, useProgram} from '@jakubmazanec/cli';
+import chalk from 'chalk';
+import {Box, Text} from 'ink';
+import {useEffect, useState} from 'react';
+
+import {runUpdateWorkspace} from './runUpdateWorkspace.js';
+import {type updateWorkspaceCommand} from './updateWorkspaceCommand.js';
+import {type Workspace} from '../../workspace.js';
+
+export type UpdateWorkspaceProps = {
+  args: CommandArguments<typeof updateWorkspaceCommand>;
+  workspace: Workspace | Workspace<false>;
+};
+
+export function UpdateWorkspace({workspace, args}: UpdateWorkspaceProps) {
+  let [isFinished, setIsFinished] = useState(false);
+  let [jobs, setJobs] = useState<string[]>([]);
+  let {exit} = useProgram();
+
+  useEffect(() => {
+    let subscription = runUpdateWorkspace({workspace, args}).subscribe({
+      next(value) {
+        setJobs((previousJobs) => [...previousJobs, value]);
+      },
+      error(error) {
+        exit(error);
+      },
+      complete() {
+        setIsFinished(true);
+      },
+    });
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [args, exit, workspace]);
+
+  return (
+    <Box flexDirection="column">
+      <Text>{`Updating workspace at ${chalk[colors.info](workspace.path)}.`}</Text>
+
+      <Box marginTop={1} flexDirection="column">
+        <Header showSpinner={!isFinished} icon={icons.success} marginBottom={1}>
+          <Text>Updating workspace...</Text>
+        </Header>
+
+        {jobs.map((job) => (
+          <Text key={job}>{`${icons.info} ${job}`}</Text>
+        ))}
+      </Box>
+
+      {isFinished ? (
+        <Header marginTop={1} icon={icons.success}>
+          <Text>Done.</Text>
+        </Header>
+      ) : null}
+    </Box>
+  );
+}

package/src/commands/update-workspace/runUpdateWorkspace.ts

@@ -0,0 +1,36 @@
+import {type CommandArguments} from '@jakubmazanec/cli';
+import Observable from 'zen-observable';
+
+import {type updateWorkspaceCommand} from './updateWorkspaceCommand.js';
+import {type Workspace} from '../../workspace.js';
+
+export type UpdateWorkspaceAndProjectsOptions = {
+  workspace: Workspace | Workspace<false>;
+  args: CommandArguments<typeof updateWorkspaceCommand>;
+};
+
+export type UpdateWorkspaceAndProjectsStatus = string;
+
+export function runUpdateWorkspace({workspace, args}: UpdateWorkspaceAndProjectsOptions) {
+  return new Observable<UpdateWorkspaceAndProjectsStatus>((observer) => {
+    (async () => {
+      // update workspace
+      observer.next('Updating workspace');
+
+      await workspace.update({args});
+
+      // update projects
+      for (let project of workspace.projects) {
+        observer.next(`Updating project ${project.name ?? '?'}`);
+
+        await project.update({args});
+      }
+    })()
+      .then(() => {
+        observer.complete();
+      })
+      .catch((error) => {
+        observer.error(error);
+      });
+  });
+}

package/src/commands/update-workspace/updateWorkspaceCommand.tsx

@@ -0,0 +1,27 @@
+import {Command} from '@jakubmazanec/cli';
+import path from 'node:path';
+
+import {UpdateWorkspace} from './UpdateWorkspace.js';
+import {Workspace} from '../../workspace.js';
+
+export const updateWorkspaceCommand = new Command(
+  'update workspace',
+  async (args, program) => {
+    let resolvedPath = path.resolve(process.cwd(), args.options.path ?? '');
+    let workspace = await Workspace.findAndRead(resolvedPath);
+
+    if (!workspace) {
+      throw new Error(`No workspace found at "${resolvedPath}"!`);
+    }
+
+    await program.renderElement(<UpdateWorkspace workspace={workspace} args={args} />);
+  },
+  {
+    description: 'Updates files in a workspace.',
+    options: {
+      path: {
+        type: 'string',
+      },
+    },
+  },
+);

package/src/commands/update-workspace.ts

@@ -0,0 +1,3 @@
+export * from './update-workspace/runUpdateWorkspace.js';
+export * from './update-workspace/UpdateWorkspace.js';
+export * from './update-workspace/updateWorkspaceCommand.js';

package/src/commands.ts

@@ -0,0 +1,3 @@
+export * from './commands/create-project.js';
+export * from './commands/create-workspace.js';
+export * from './commands/update-workspace.js';

package/src/constants.ts

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import url from 'node:url';
+
+let directory = path.dirname(url.fileURLToPath(import.meta.url));
+
+export const PACKAGE_PATH = path.resolve(directory, '..');
+
+// import path from 'node:path';
+// import url from 'node:url';
+
+// let directory = path.dirname(url.fileURLToPath(import.meta.url));
+
+export const CARSON_CONFIG_DIRECTORY = '.carson';
+export const PROJECT_CONFIG_FILENAME = 'project.json';
+export const WORKSPACE_CONFIG_FILENAME = 'workspace.json';
+export const SNAPSHOTS_FILENAME = '.snapshots';
+
+export const TEMPLATES_PATH = 'templates';
+
+// config files in carson template package
+export const TEMPLATE_CONFIG_FILENAME = 'config.json';

package/src/main.ts

@@ -0,0 +1,3 @@
+export * from './commands.js';
+export * from './template.js';
+export * from './workspace.js';

package/src/modules.d.ts

@@ -0,0 +1 @@
+declare module 'prettier-plugin-packagejson';

package/src/run.ts

@@ -0,0 +1,21 @@
+import {Program, getProgramDetail} from '@jakubmazanec/cli';
+import {readPackageJson} from '@jakubmazanec/zod-utils';
+import path from 'node:path';
+
+import {createWorkspaceCommand, updateWorkspaceCommand, createProjectCommand} from './commands.js';
+import {PACKAGE_PATH} from './constants.js';
+
+let programDetail = getProgramDetail(
+  await readPackageJson(path.join(PACKAGE_PATH, 'package.json'), {throwOnZodError: true}),
+);
+
+let program = new Program({
+  ...programDetail,
+  name: 'Carson',
+});
+
+program.addCommand(createWorkspaceCommand);
+program.addCommand(createProjectCommand);
+program.addCommand(updateWorkspaceCommand);
+
+await program.run(process.argv.slice(2));

package/src/template/CarsonTemplate.ts

@@ -0,0 +1,11 @@
+import {type Template} from '@jakubmazanec/template';
+
+import {type CarsonTemplateConfig} from './CarsonTemplateConfig.js';
+import {type templateAttributesSchema} from './TemplateAttributes.js';
+import {type templateDataSchema} from './TemplateData.js';
+
+export type CarsonTemplate = {
+  name: string;
+  config: CarsonTemplateConfig;
+  files: Array<Template<typeof templateAttributesSchema, typeof templateDataSchema>>;
+};

package/src/template/CarsonTemplateConfig.ts

@@ -0,0 +1,12 @@
+import {z} from 'zod';
+
+export const carsonTemplateConfigSchema = z
+  .object({
+    disallowMultiProjectWorkspace: z.boolean().optional(),
+    disallowSingleProjectWorkspace: z.boolean().optional(),
+
+    // TODO: add extends property to allow reuisng template files from another carson template
+  })
+  .strict();
+
+export type CarsonTemplateConfig = z.infer<typeof carsonTemplateConfigSchema>;

package/src/template/TemplateAttributes.ts

@@ -0,0 +1,16 @@
+import {z} from 'zod';
+
+export const templateAttributesSchema = z
+  .object({
+    // TODO: add strategy 'none' so when you using template A that extends template B, you can overwrite template files to no-op
+    strategy: z.union([
+      z.literal('create'),
+      z.literal('overwrite'),
+      z.literal('merge'),
+      z.literal('check'),
+      z.tuple([z.literal('insert'), z.string()]),
+    ]),
+  })
+  .strict();
+
+export type TemplateAttributes = z.infer<typeof templateAttributesSchema>;

package/src/template/TemplateData.ts

@@ -0,0 +1,17 @@
+import {z} from 'zod';
+
+import {carsonTemplateConfigSchema} from './CarsonTemplateConfig.js';
+import {Project} from '../workspace/Project.js';
+import {Workspace} from '../workspace/Workspace.js';
+
+// TODO: what about template data for workspace and template data for project, so we can get rid of the `.optional()`?
+export const templateDataSchema = z
+  .object({
+    workspace: z.instanceof(Workspace).optional(),
+    project: z.instanceof(Project).optional(),
+    args: z.record(z.unknown()).optional(),
+    templateConfig: carsonTemplateConfigSchema.optional(),
+  })
+  .strict();
+
+export type TemplateData = z.infer<typeof templateDataSchema>;

package/src/template/TemplateRender.ts

@@ -0,0 +1,9 @@
+import {type TemplateRender as BaseTemplateRender} from '@jakubmazanec/template';
+
+import {type templateAttributesSchema} from './TemplateAttributes.js';
+import {type templateDataSchema} from './TemplateData.js';
+
+export type TemplateRender = BaseTemplateRender<
+  typeof templateAttributesSchema,
+  typeof templateDataSchema
+>;

package/src/template/TemplateRenderSnapshot.ts

@@ -0,0 +1,13 @@
+import {templateAttributesSchema as baseTemplateAttributesSchema} from '@jakubmazanec/template';
+import {z} from 'zod';
+
+import {templateAttributesSchema} from './TemplateAttributes.js';
+
+export const templateRenderSnapshotSchema = z
+  .object({
+    attributes: baseTemplateAttributesSchema.pick({to: true}).merge(templateAttributesSchema),
+    content: z.string(),
+  })
+  .strict();
+
+export type TemplateRenderSnapshot = z.infer<typeof templateRenderSnapshotSchema>;

package/src/template/TemplateRenderSnapshots.ts

@@ -0,0 +1,7 @@
+import {type z} from 'zod';
+
+import {templateRenderSnapshotSchema} from './TemplateRenderSnapshot.js';
+
+export const templateRenderSnapshotsSchema = templateRenderSnapshotSchema.array();
+
+export type TemplateRenderSnapshots = z.infer<typeof templateRenderSnapshotsSchema>;

package/src/template/TemplateRenders.ts

@@ -0,0 +1,3 @@
+import {type TemplateRender} from './TemplateRender.js';
+
+export type TemplateRenders = TemplateRender[];

package/src/template/applyTemplateRenders.ts

@@ -0,0 +1,89 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import prettier from 'prettier';
+
+import {createFileUsingTemplateRender} from './createFileUsingTemplateRender.js';
+import {deleteFileUsingTemplateRender} from './deleteFileUsingTemplateRender.js';
+import {insertUsingTemplateRender} from './insertUsingTemplateRender.js';
+import {loadTemplateRenderSnapshots} from './loadTemplateRenderSnapshots.js';
+import {mergeFileUsingTemplateRender} from './mergeFileUsingTemplateRender.js';
+import {overwriteFileUsingTemplateRender} from './overwriteFileUsingTemplateRender.js';
+import {saveTemplateRenderSnapshots} from './saveTemplateRenderSnapshots.js';
+import {type TemplateRenders} from './TemplateRenders.js';
+import {uninsertUsingTemplateRender} from './uninsertUsingTemplateRender.js';
+import {unmergeFileUsingTemplateRender} from './unmergeFileUsingTemplateRender.js';
+import {CARSON_CONFIG_DIRECTORY, SNAPSHOTS_FILENAME} from '../constants.js';
+
+export type ApplyTemplateRendersOptions = {
+  templateRenders: TemplateRenders;
+  path: string;
+  ignoreCreateStrategies: boolean;
+  ignoreCheckStrategies: boolean;
+};
+
+export async function applyTemplateRenders({
+  templateRenders,
+  path: targetPath,
+  ignoreCheckStrategies,
+  ignoreCreateStrategies,
+}: ApplyTemplateRendersOptions) {
+  // we need to clear Prettier cache, because we are changing file system
+  prettier.clearConfigCache();
+
+  let templateRenderSnapshotsPath = path.join(
+    targetPath,
+    CARSON_CONFIG_DIRECTORY,
+    SNAPSHOTS_FILENAME,
+  );
+
+  if (await fs.pathExists(templateRenderSnapshotsPath)) {
+    let templateRenderSnapshots = await loadTemplateRenderSnapshots(templateRenderSnapshotsPath);
+
+    for (let templateRenderSnapshot of templateRenderSnapshots) {
+      if (templateRenderSnapshot.attributes.strategy === 'overwrite') {
+        await deleteFileUsingTemplateRender(templateRenderSnapshot, targetPath);
+      }
+
+      if (templateRenderSnapshot.attributes.strategy === 'merge') {
+        await unmergeFileUsingTemplateRender(templateRenderSnapshot, targetPath);
+      }
+
+      if (templateRenderSnapshot.attributes.strategy[0] === 'insert') {
+        await uninsertUsingTemplateRender(templateRenderSnapshot, targetPath);
+      }
+    }
+  }
+
+  if (!ignoreCreateStrategies) {
+    for (let templateRender of templateRenders) {
+      if (templateRender.attributes.strategy === 'create') {
+        await createFileUsingTemplateRender(templateRender, targetPath);
+      }
+    }
+  }
+
+  for (let templateRender of templateRenders) {
+    if (templateRender.attributes.strategy === 'overwrite') {
+      await overwriteFileUsingTemplateRender(templateRender, targetPath);
+    }
+
+    if (templateRender.attributes.strategy === 'merge') {
+      await mergeFileUsingTemplateRender(templateRender, targetPath);
+    }
+
+    if (templateRender.attributes.strategy[0] === 'insert') {
+      await insertUsingTemplateRender(templateRender, targetPath);
+    }
+
+    if (!ignoreCheckStrategies && templateRender.attributes.strategy === 'check') {
+      let to = path.join(targetPath, templateRender.attributes.to);
+      let doesToExist = await fs.pathExists(to);
+
+      if (!doesToExist) {
+        throw new Error(`File "${to}" doesn't exist!`);
+      }
+    }
+  }
+
+  await saveTemplateRenderSnapshots(templateRenders, templateRenderSnapshotsPath);
+}

package/src/template/createFileUsingTemplateRender.ts

@@ -0,0 +1,12 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+
+import {prettify} from './internals.js';
+import {type TemplateRender} from './TemplateRender.js';
+
+export async function createFileUsingTemplateRender(render: TemplateRender, basePath: string) {
+  let to = path.join(basePath, render.attributes.to);
+
+  await fs.ensureDir(path.dirname(to));
+  await fs.writeFile(to, await prettify(render.content, to), {encoding: 'utf8'});
+}

package/src/template/deleteFileUsingTemplateRender.ts

@@ -0,0 +1,15 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+
+import {type TemplateRenderSnapshot} from './TemplateRenderSnapshot.js';
+
+export async function deleteFileUsingTemplateRender(
+  render: TemplateRenderSnapshot,
+  basePath: string,
+) {
+  let to = path.join(basePath, render.attributes.to);
+
+  if (await fs.pathExists(to)) {
+    await fs.rm(to);
+  }
+}

package/src/template/importCarsonTemplate.ts

@@ -0,0 +1,13 @@
+import {parseTemplateId} from './parseTemplateId.js';
+
+type Module = {
+  [key: string]: unknown;
+  default: unknown;
+};
+
+export async function importCarsonTemplate(templateId: string) {
+  let [moduleId] = parseTemplateId(templateId);
+  let {default: _, ...moduleWithoutDefault} = (await import(moduleId)) as Module;
+
+  return moduleWithoutDefault;
+}

package/src/template/insertUsingTemplateRender.ts

@@ -0,0 +1,33 @@
+import fs from 'fs-extra';
+import _ from 'lodash';
+import path from 'node:path';
+
+import {prettify} from './internals.js';
+import {type TemplateRender} from './TemplateRender.js';
+
+export async function insertUsingTemplateRender(render: TemplateRender, basePath: string) {
+  let to = path.join(basePath, render.attributes.to);
+  let extension = path.extname(to);
+
+  switch (extension) {
+    case '.md': {
+      let targetFile = await fs.readFile(to, {encoding: 'utf8'});
+      let newContent = `<!-- ${render.attributes.strategy[1]} -->${render.content}<!-- ${render.attributes.strategy[1]} -->`;
+      let oldContentRegexp = new RegExp(
+        `<!--\\s*${_.escapeRegExp(
+          render.attributes.strategy[1],
+        )}\\s-->[\\s\\S]*<!--\\s*${_.escapeRegExp(render.attributes.strategy[1])}\\s-->`,
+        'u',
+      );
+      let newFile = targetFile.replace(oldContentRegexp, newContent);
+
+      await fs.writeFile(to, await prettify(newFile, to), {encoding: 'utf8'});
+
+      break;
+    }
+
+    default: {
+      throw new Error(`File extension "${extension}" is not supported!`);
+    }
+  }
+}

package/src/template/internals/merge.ts

@@ -0,0 +1,44 @@
+/**
+ * Merges two JSON-like variables. Only simple objects, not arrays, are merged recursively.
+ */
+export function merge(a: unknown, b: unknown) {
+  if (b === undefined || b == null) {
+    return a;
+  }
+
+  if (typeof b !== 'object' || Array.isArray(b)) {
+    return a;
+  }
+
+  if (a === undefined || a == null) {
+    return a;
+  }
+
+  if (typeof a !== 'object' || Array.isArray(a)) {
+    return a;
+  }
+
+  const newA: Record<string, unknown> = {...a};
+
+  for (let [key, value] of Object.entries(b)) {
+    if (
+      (a as Record<string, unknown>)[key] &&
+      typeof (a as Record<string, unknown>)[key] === 'object' &&
+      !Array.isArray((a as Record<string, unknown>)[key]) &&
+      (b as Record<string, unknown>)[key] &&
+      typeof (b as Record<string, unknown>)[key] === 'object' &&
+      !Array.isArray((b as Record<string, unknown>)[key])
+    ) {
+      const result = merge(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      );
+
+      newA[key] = result;
+    } else {
+      newA[key] = value;
+    }
+  }
+
+  return newA;
+}

package/src/template/internals/prettify.ts

@@ -0,0 +1,24 @@
+import prettier from 'prettier';
+import packageJsonPrettierPlugin from 'prettier-plugin-packagejson';
+
+const NO_INFERRED_PARSER = /parser.*inferred/i;
+
+export async function prettify(content: string, targetPath: string) {
+  let prettifiedContent = content;
+
+  try {
+    let prettierOptions = await prettier.resolveConfig(targetPath, {editorconfig: true});
+
+    prettifiedContent = prettier.format(content, {
+      ...prettierOptions,
+      filepath: targetPath,
+      plugins: [packageJsonPrettierPlugin],
+    });
+  } catch (error: unknown) {
+    if (!NO_INFERRED_PARSER.test((error as Error).message)) {
+      throw error;
+    }
+  }
+
+  return prettifiedContent;
+}

package/src/template/internals/unmerge.ts

@@ -0,0 +1,48 @@
+/**
+ * Reverts {@linkcode merge}.
+ */
+export function unmerge(a: unknown, b: unknown) {
+  if (b === undefined || b == null) {
+    return a;
+  }
+
+  if (typeof b !== 'object' || Array.isArray(b)) {
+    return a;
+  }
+
+  if (a === undefined || a == null) {
+    return a;
+  }
+
+  if (typeof a !== 'object' || Array.isArray(a)) {
+    return a;
+  }
+
+  const newA: Record<string, unknown> = {};
+
+  for (let [key] of Object.entries(a)) {
+    if (!Object.hasOwn(b, key)) {
+      newA[key] = (a as Record<string, unknown>)[key];
+
+      continue;
+    } else if (
+      (a as Record<string, unknown>)[key] &&
+      typeof (a as Record<string, unknown>)[key] === 'object' &&
+      !Array.isArray((a as Record<string, unknown>)[key]) &&
+      (b as Record<string, unknown>)[key] &&
+      typeof (b as Record<string, unknown>)[key] === 'object' &&
+      !Array.isArray((b as Record<string, unknown>)[key])
+    ) {
+      const result = unmerge(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      );
+
+      if (Object.keys(result as Record<string, unknown>).length > 0) {
+        newA[key] = result;
+      }
+    }
+  }
+
+  return newA;
+}

package/src/template/internals.ts

@@ -0,0 +1,3 @@
+export * from './internals/merge.js';
+export * from './internals/prettify.js';
+export * from './internals/unmerge.js';

package/src/template/loadTemplateRenderSnapshots.ts

@@ -0,0 +1,18 @@
+import {inflateSync, strFromU8} from 'fflate';
+import fs from 'fs-extra';
+
+import {templateRenderSnapshotsSchema} from './TemplateRenderSnapshots.js';
+
+export async function loadTemplateRenderSnapshots(templateRenderSnapshotsPath: string) {
+  let compressedSnapshots = await fs.readFile(templateRenderSnapshotsPath);
+  let decompressedSnapshots = inflateSync(new Uint8Array(compressedSnapshots));
+  let parsingResult = templateRenderSnapshotsSchema.safeParse(
+    JSON.parse(strFromU8(decompressedSnapshots)),
+  );
+
+  if (!parsingResult.success) {
+    throw parsingResult.error;
+  }
+
+  return parsingResult.data;
+}

package/src/template/mergeFileUsingTemplateRender.ts

@@ -0,0 +1,39 @@
+import {type Json} from '@jakubmazanec/zod-utils';
+import fs from 'fs-extra';
+import json from 'json5';
+import path from 'node:path';
+import yaml from 'yaml';
+
+import {merge, prettify} from './internals.js';
+import {type TemplateRender} from './TemplateRender.js';
+
+export async function mergeFileUsingTemplateRender(render: TemplateRender, basePath: string) {
+  let to = path.join(basePath, render.attributes.to);
+  let extension = path.extname(to);
+
+  switch (extension) {
+    case '.json': {
+      let targetFile = (await fs.readJson(to)) as Json;
+      let fileToMerge = json.parse<Json>(render.content);
+      let newFile = JSON.stringify(merge(targetFile, fileToMerge));
+
+      await fs.writeFile(to, await prettify(newFile, to), {encoding: 'utf8'});
+
+      break;
+    }
+
+    case '.yaml': {
+      let targetFile = yaml.parse(await fs.readFile(to, {encoding: 'utf8'})) as unknown;
+      let fileToMerge = yaml.parse(render.content) as unknown;
+      let newFile = yaml.stringify(merge(targetFile, fileToMerge));
+
+      await fs.writeFile(to, await prettify(newFile, to), {encoding: 'utf8'});
+
+      break;
+    }
+
+    default: {
+      throw new Error(`File extension "${extension}" is not supported!`);
+    }
+  }
+}

package/src/template/overwriteFileUsingTemplateRender.ts

@@ -0,0 +1,12 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+
+import {prettify} from './internals.js';
+import {type TemplateRender} from './TemplateRender.js';
+
+export async function overwriteFileUsingTemplateRender(render: TemplateRender, basePath: string) {
+  let to = path.join(basePath, render.attributes.to);
+
+  await fs.ensureDir(path.dirname(to));
+  await fs.writeFile(to, await prettify(render.content, to), {encoding: 'utf8'});
+}

package/src/template/parseTemplateId.ts

@@ -0,0 +1,9 @@
+export function parseTemplateId(value: string): [moduleId: string, templateName: string] {
+  let parts = value.split(':');
+
+  if (!parts[0] || !parts[1]) {
+    throw new Error('Template id is invalid!');
+  }
+
+  return [parts[0], parts[1]];
+}