洪 民憙 (Hong Minhee)

Hello, I'm an open source software engineer in my late 30s living in #Seoul, #Korea, and an avid advocate of #FLOSS and the #fediverse.

I'm the creator of @fedify, an #ActivityPub server framework in #TypeScript, @hollo, an ActivityPub-enabled microblogging software for single users, and @botkit, a simple ActivityPub bot framework.

I'm also very interested in East Asian languages (so-called #CJK) and #Unicode. Feel free to talk to me in #English, #Korean (#한국어), or #Japanese (#日本語), or even in Literary Chinese (#文言文, #漢文)!

#introduction

安寧(안녕)하세요, 저는 서울에 살고 있는 30代(대) 後半(후반) 오픈 소스 소프트웨어 엔지니어이며, 自由(자유)·오픈 소스 소프트웨어와 聯合宇宙(연합우주)(fediverse)의 熱烈(열렬)한 支持者(지지자)입니다.

저는 TypeScript用(용) ActivityPub 서버 프레임워크인 @fedify 프로젝트와 싱글 유저用(용) ActivityPub 마이크로블로그인 @hollo 프로젝트와 ActivityPub 봇 프레임워크인 @botkit 프로젝트의 製作者(제작자)이기도 합니다.

저는 東(동)아시아 言語(언어)(이른바 #CJK)와 유니코드에도 關心(관심)이 많습니다. 聯合宇宙(연합우주)에서는 國漢文混用體(국한문 혼용체)를 쓰고 있어요! 제게 韓國語(한국어)나 英語(영어), 日本語(일본어)로 말을 걸어주세요. (아니면, 漢文(한문)으로도!)

#툿친소 #연친소 #별친소

こんにちは、私はソウルに住んでいる30代後半のオープンソースソフトウェアエンジニアで、自由・オープンソースソフトウェアとフェディバースの熱烈な支持者です。名前は洪 民憙（ホン・ミンヒ）です。

私はTypeScript用のActivityPubサーバーフレームワークである「@fedify」と、ActivityPubをサポートする1人用マイクロブログである 「@hollo」と、ActivityPubのボットを作成する為のシンプルなフレームワークである「@botkit」の作者でもあります。

私は東アジア言語（いわゆるCJK）とUnicodeにも興味が多いです。日本語、英語、韓国語で話しかけてください。（または、漢文でも！）

#自己紹介

Also, LogTape - a javascript / typescript logger - is very nice. It's not fedi-specific, worth a look.

https://logtape.org/intro

Finished the basic tutorial for #Fedify - I can now Follow and Unfollow the "me" account. Lots of useful debugging and dev tools built in, too.

I think what's most interesting about this framework is that there are quite a few AP vocabulary activitites available to you above and beyond the Mastodon mainstream.

Would love to tinker around with Offer, Reject, Listen, Question, Read

https://fedify.dev/tutorial/basics

[定期] GitHubスポンサーも募集しています
https://github.com/sponsors/ttrace?o=sd&sc=t

연합우주라 우주 관련된 단어가 많이 쓰이는게 좋다

最近(최근) 한창 開發中(개발중)인 Fedify 基盤(기반) ActivityPub 서비스 2個(개):

• Kosmo: @robin_maki 님이 만들고 계시는 次世代(차세대) ActivityPub 基盤(기반) SNS
• Cosmoslide: @kodingwarrior 님이 만들고 계시는 ActivityPub 基盤(기반) 슬라이드 共有(공유) 서비스

完全(완전) 期待中(기대중)!!

(寫眞(사진)에 肉食(육식) 包含(포함).)

袁枚(원매)의 《隨園食單(수원식단)》을 主(주)로 硏究(연구)한 申桂淑(신계숙) 敎授(교수)가 直接(직접) 運營(운영)하는 淸代(청대) 中華料理(중화요리) 專門店(전문점) 桂香閣(계향각)에 다녀왔다. (寫眞(사진)에 肉食(육식) 包含(포함).)

N줄 요약

• 연합우주 소프트웨어 개밥먹기하면서 개발중
• 로컬호스트에서 돌리고 있고, tailscale로 터널링 중이며 몇몇 인스턴스 계정에 팔로워로 들어가있음.
• 몇몇 인스턴스에서는 아마 위의 사유로 계속 retry 되고 있는 Activity가 있을 것인데, 해당 인스턴스 모더레이터분들 괜찮으신지?

요즘 #cosmoslide (https://github.com/cosmoslide/cosmoslide) 개발하면서 들고 있는 생각....

대부분의 액티비티펍 소프트웨어 인스턴스는 멀쩡하게 365일 24시간 동일한 위치에서 운영이 되고 있다고 가정이 된다. 내가 글을 올리면, 나를 팔로우 중인 모든 사람들의 inbox에 내가 글을 올렸다(Create(Note))는 Activity가 전달이 되는데, 각자가 운영되고 있는 서버 인스턴스가 멀쩡히 살아있다면.... 딱히 문제가 되지는 않는다.

문제는, 게시글을 작성하는 시점에 팔로워 중 누군가의 인스턴스가 죽어있을때도 있다는 점이다. 그런 경우를 대비해서 exponential backoff를 쓰든 아무튼 fallback 알고리즘이 동작하긴 하는데, 서버가 살아나면 당연히 전달이야 잘 되긴 한다. 그런데, Activity 전달이 실패하는 일이 잦으면 어떤 액티비티펍 소프트웨어를 쓰던간에 retry를 하기 위해서 계속해서 Queue에 쌓이고, 최종적으로는 Queue에 쌓인 것 때문에 적지 않은 오버헤드가 있을 것 같은데 모더레이터의 입장에선 어느 정도까지 감안할 수 있는가? 라는 생각이 문득 들었다.

사실 내가 왜 이런 글을 쓰고 있냐면, 위에서도 언급했다시피, 로컬호스트에서 실제로 서비스를 (맥북이 켜져있을때만) 서빙하고 있고 그걸 Tailscale로 연결해서 터널링을 하고 있다. 즉, 맥북을 켜놓고 있으면 Create(Note) Activity가 정상적으로 잘 전달되고, 맥북이 꺼져있으면 Activity 전달이 안되고 있다. 실제로, 이런 맥락에서 지금 테스트 중인 두 개의 인스턴스가 있다. 이런 실험적인 시도를 하면서 이래도 되는게 맞나 싶은 생각도 들고는 있다. 맥북을 켜놓으면, retry되고 있는 것도 다 consume되긴 하겠지만.... 찝찝하긴 찝찝하다.

개발하는 입장이라고 선해를 할 수는 있어도, 비뚤어진 관점에서 해석하면 누군가는 어뷰징의 관점으로 해석할 수 있는 가능성이 적지는 않다고 생각하고 있다. 이런 경우엔 모더레이터되는 분들한테, 내가 이런 tailscale 도메인으로 서빙하고 있다고 통지라도 하는게 나으려나... 아니면, 내가 구매해놓은 도메인을 tailscale 도메인으로 CNAME 걸어놓고 "이런 도메인으로 서비스 걸어놓을 예정이니까 이 도메인만은 제발 차단하지 말아주십쇼 헤헤" 라고 해야하나... 아예 서버를 만드는거다보니까 이런 고려사항이 생기는 것 같다.

근데, 한 편으로는 이런 생각이 든다. 물리적인 서버의 위치를 옮길 가능성이 많은 환경(예를 들면, 전시 상황)이면 어떡하지? ActivityPub이 사실은 분산된 웹 환경을 위해 나온 프로토콜이긴 하지만, 분산된 웹 환경이라는게 물리적으로 각자 다른 위치에 오랫동안 배치가 되어 있는 서버 뿐만이 아니라 위치가 자주 바뀔 수 있는 서버도 연합의 대상으로 포함이 될 수 있다면? 어떤 공상과학 영화(ex. 터미네이터4)들을 보면, 저항군이 독자적인 라디오 기지국 같은거 만들고 위치도 매번 다른 곳으로 옮기고 주파수를 매번 다르게 설정하면서 소식전달하는 모습을 볼 수 있는데, 액티비티펍도 어떻게 보면 그걸 고려한 설계도 포함될 수 있지 않나... 그런 생각도 든다..

@hongminhee @regendans looks excellent!

클러스터화는 단점이기도 하지만 장점이기도 한게 제가 생각하기에 다른 커뮤니티 서비스랑 트위터류의 가장 큰 차이점은 적당한? 느슨한? 클러스터화라고 생각하거든요 트위터만 봐도 인플루언서-like하게 사용하는 사람도 자기들끼리 노는 사람도 있는데 되게 그런 사람들간에 사용 형태와 목적이 판이하게 다를탠데 동시에 같은 트위터에 존재하면서도 디스코드같은 아예 클러스터가 완전히 분리된 동네하고는 다르게 그 클러스터들 사이에도 느슨한 연결고리가 존재한다는게 매력이라고 생각해요

초보자에게 서버를 골라야 하는 큰 장벽이 없으면서 서버는 기술적 지식 없이 만들 수 있으면 좋겠다...

Stop writing CLI validation. Parse it right the first time https://lobste.rs/s/deaem7 #javascript #programming
https://hackers.pub/@hongminhee/2025/stop-writing-cli-validation-parse-it-right-the-first-time

Every CLI tool has the same validation code hidden somewhere:

• “option A requires option B”
• “can't use X and Y together”
• “this only works in production mode”

I got tired of writing it. So I built something that makes it unnecessary.

https://hackers.pub/@hongminhee/2025/stop-writing-cli-validation-parse-it-right-the-first-time

The concept of the "male socialization" of trans women is deeply problematic. Most of the time when people use that phrase, it's to degender and degrade trans women and make them out to be less women than their cis counterparts. When people go down that path of reasoning, it's usually toxic and leads to a lot of wrong conclusions.

We often never got the kind of male privilege that people assume we did because we looked like dudes. The reality is that bullies often pick up on our gender differences even if we don't and it can get dark. We also didn't have boyhoods. Just because our parents dressed us in blue and bought us baseball hats doesn't mean we have the same relationship to those things that cis guys do. Often, it's some weird, fucked up mix.

But...

We also didn't have "normal" girlhoods, either, and this can leave a huge hole.

One of the things I'm constantly self-conscious about when trying to relate to cis women is that there's this vast swath of girlhood experiences that they just take for granted and assume every woman has.

I don't.

Now, yes, those assumptions are generally rubbish because they're heavily dependant on culture, race, and class. But even then, there are still common threads. I'm missing all the threads.

When talking to other women, I rely a lot on the experiences I've had over just the last 3 years as well as things I've read and things I watched my sisters go through. I have a few distinctly girl childhood experiences I can draw on as well but not many. The whole time I worry that I'm going to slip up and say the wrong thing. Or maybe they'll say something that assumes a shared experience and I'll just sit there dumbfounded because I know that's a common girl experience but I've got no clue.

Sometimes those interactions can be weirdly affirming because you know they see you as a girl subconsciously when they start making those assumptions rather than assuming "male socialization" (🤮) but it can still leave you dumbfounded and speechless.

The only thing I can say is that it does seem to be getting better with time, both as I form new authentically feminine experiences as an adult and as I grow in confidence. But still it's hard and I feel that hole in basically every relationship I have with a cis woman. 😢

Did you know your MacBook has a sensor that knows the exact angle of the screen hinge?

It’s not exposed as a public API, but I figured out a way to read it and make it sound like an old wooden door.

Source code and a downloadable app to try it yourself: https://github.com/samhenrigold/LidAngleSensor

I have this bad habit. When something annoys me enough times, I end up building a library for it. This time, it was CLI validation code.

See, I spend a lot of time reading other people's code. Open source projects, work stuff, random GitHub repos I stumble upon at 2 AM. And I kept noticing this thing: every CLI tool has the same ugly validation code tucked away somewhere. You know the kind:

if (!opts.server && opts.port) {
  throw new Error("--port requires --server flag");
}

if (opts.server && !opts.port) {
  opts.port = 3000; // default port
}

// wait, what if they pass --port without a value?
// what if the port is out of range?
// what if...

It's not even that this code is hard to write. It's that it's everywhere. Every project. Every CLI tool. The same patterns, slightly different flavors. Options that depend on other options. Flags that can't be used together. Arguments that only make sense in certain modes.

And here's what really got me: we solved this problem years ago for other types of data. Just… not for CLIs.

The problem with validation

There's this blog post that completely changed how I think about parsing. It's called Parse, don't validate by Alexis King. The gist? Don't parse data into a loose type and then check if it's valid. Parse it directly into a type that can only be valid.

Think about it. When you get JSON from an API, you don't just parse it as any and then write a bunch of if-statements. You use something like Zod to parse it directly into the shape you want. Invalid data? The parser rejects it. Done.

But with CLIs? We parse arguments into some bag of properties and then spend the next 100 lines checking if that bag makes sense. It's backwards.

So yeah, I built Optique. Not because the world desperately needed another CLI parser (it didn't), but because I was tired of seeing—and writing—the same validation code everywhere.

Three patterns I was sick of validating

Dependent options

This one's everywhere. You have an option that only makes sense when another option is enabled.

The old way? Parse everything, then check:

const opts = parseArgs(process.argv);
if (!opts.server && opts.port) {
  throw new Error("--port requires --server");
}
if (opts.server && !opts.port) {
  opts.port = 3000;
}
// More validation probably lurking elsewhere...

With Optique, you just describe what you want:

const config = withDefault(
  object({
    server: flag("--server"),
    port: option("--port", integer()),
    workers: option("--workers", integer())
  }),
  { server: false }
);

Here's what TypeScript infers for config's type:

type Config = 
  | { readonly server: false }
  | { readonly server: true; readonly port: number; readonly workers: number }

The type system now understands that when server is false, port literally doesn't exist. Not undefined, not null—it's not there. Try to access it and TypeScript yells at you. No runtime validation needed.

Mutually exclusive options

Another classic. Pick one output format: JSON, YAML, or XML. But definitely not two.

I used to write this mess:

if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) {
  throw new Error('Choose only one output format');
}

(Don't judge me, you've written something similar.)

Now?

const format = or(
  map(option("--json"), () => "json" as const),
  map(option("--yaml"), () => "yaml" as const),
  map(option("--xml"), () => "xml" as const)
);

The or() combinator means exactly one succeeds. The result is just "json" | "yaml" | "xml". A single string. Not three booleans to juggle.

Environment-specific requirements

Production needs auth. Development needs debug flags. Docker needs different options than local. You know the drill.

Instead of a validation maze, you just describe each environment:

const envConfig = or(
  object({
    env: constant("prod"),
    auth: option("--auth", string()),      // Required in prod
    ssl: option("--ssl"),
    monitoring: option("--monitoring", url())
  }),
  object({
    env: constant("dev"),
    debug: optional(option("--debug")),    // Optional in dev
    verbose: option("--verbose")
  })
);

No auth in production? Parser fails immediately. Trying to access --auth in dev mode? TypeScript won't let you—the field doesn't exist on that type.

“But parser combinators though…”

I know, I know. “Parser combinators” sounds like something you'd need a CS degree to understand.

Here's the thing: I don't have a CS degree. Actually, I don't have any degree. But I've been using parser combinators for years because they're actually… not that hard? It's just that the name makes them sound way scarier than they are.

I'd been using them for other stuff—parsing config files, DSLs, whatever. But somehow it never clicked that you could use them for CLI parsing until I saw Haskell's optparse-applicative. That was a real “wait, of course” moment. Like, why are we doing this any other way?

Turns out it's stupidly simple. A parser is just a function. Combinators are just functions that take parsers and return new parsers. That's it.

// This is a parser
const port = option("--port", integer());

// This is also a parser (made from smaller parsers)
const server = object({
  port: port,
  host: option("--host", string())
});

// Still a parser (parsers all the way down)
const config = or(server, client);

No monads. No category theory. Just functions. Boring, beautiful functions.

TypeScript does the heavy lifting

Here's the thing that still feels like cheating: I don't write types for my CLI configs anymore. TypeScript just… figures it out.

const cli = or(
  command("deploy", object({
    action: constant("deploy"),
    environment: argument(string()),
    replicas: option("--replicas", integer())
  })),
  command("rollback", object({
    action: constant("rollback"),
    version: argument(string()),
    force: option("--force")
  }))
);

// TypeScript infers this type automatically:
type Cli = 
  | { 
      readonly action: "deploy"
      readonly environment: string
      readonly replicas: number
    }
  | { 
      readonly action: "rollback"
      readonly version: string
      readonly force: boolean
    }

TypeScript knows that if action is "deploy", then environment exists but version doesn't. It knows replicas is a number. It knows force is a boolean. I didn't tell it any of this.

This isn't just about nice autocomplete (though yeah, the autocomplete is great). It's about catching bugs before they happen. Forget to handle a new option somewhere? Code won't compile.

What actually changed for me

I've been dogfooding this for a few weeks. Some real talk:

I delete code now. Not refactor. Delete. That validation logic that used to be 30% of my CLI code? Gone. It feels weird every time.

Refactoring isn't scary. Want to know something that usually terrifies me? Changing how a CLI takes its arguments. Like going from --input file.txt to just file.txt as a positional argument. With traditional parsers, you're hunting down validation logic everywhere. With this? You change the parser definition, TypeScript immediately shows you every place that breaks, you fix them, done. What used to be an hour of “did I catch everything?” is now “fix the red squiggles and move on.”

My CLIs got fancier. When adding complex option relationships doesn't mean writing complex validation, you just… add them. Mutually exclusive groups? Sure. Context-dependent options? Why not. The parser handles it.

The reusability is real too:

const networkOptions = object({
  host: option("--host", string()),
  port: option("--port", integer())
});

// Reuse everywhere, compose differently
const devServer = merge(networkOptions, debugOptions);
const prodServer = merge(networkOptions, authOptions);
const testServer = merge(networkOptions, mockOptions);

But honestly? The biggest change is trust. If it compiles, the CLI logic works. Not “probably works” or “works unless someone passes weird arguments.” It just works.

Should you care?

If you're writing a 10-line script that takes one argument, you don't need this. process.argv[2] and call it a day.

But if you've ever:

• Had validation logic get out of sync with your actual options
• Discovered in production that certain option combinations explode
• Spent an afternoon tracking down why --verbose breaks when used with --json
• Written the same “option A requires option B” check for the fifth time

Then yeah, maybe you're tired of this stuff too.

Fair warning: Optique is young. I'm still figuring things out, the API might shift a bit. But the core idea—parse, don't validate—that's solid. And I haven't written validation code in months.

Still feels weird. Good weird.

Try it or don't

If this resonates:

• Tutorial: Build something real, see if you hate it
• Concepts: Primitives, constructs, modifiers, value parsers, the whole thing
• GitHub: The code, issues, angry rants

I'm not saying Optique is the answer to all CLI problems. I'm just saying I was tired of writing the same validation code everywhere, so I built something that makes it unnecessary.

Take it or leave it. But that validation code you're about to write? You probably don't need it.

#GNOME picks of the day:

➡️ @gnome - Official GNOME account in English

➡️ @gnome_br - GNOME in Portuguese

➡️ @haeckerfelix - GNOME developer, foundation member, author of "This Week in GNOME"

➡️ @Tuba - FOSS Fediverse app for GNOME, forked from Tootle

➡️ @WebKitGTK - GTK port of WebKit, official browser engine in GNOME

➡️ @GTK - FOSS cross-platform toolkit for creating GUIs

➡️ @EvolutionGnome - Free open source personal information manager software

🧵 1/2

참고로 Hackers' Pub은 패스키 인증을 지원하고 있습니다. ✌️

RE: https://purengom.com/2025/09/06/%ec%9d%bc%eb%b3%b8%ec%9d%80-%ed%8c%a8%ec%8a%a4%ed%82%a4%eb%a1%9c-%ec%a7%84%ea%b2%a9%ed%95%98%eb%8a%94%eb%8d%b0-%ed%95%9c%ea%b5%ad%ec%9d%80-%ec%99%9c-%ec%a0%9c%ec%9e%90%eb%a6%ac%ec%9d%b8%ea%b0%80/

@activitypub.blog
워드프레스 액티비티펍 플러그인의 한국어 설명 페이지를 대대적으로 수정했습니다.
자동번역을 전체적으로 검토하고 맥락에 맞게 수정해 가독성과 번역 품질을 대폭 개선했습니다!

이제 한국어 사용자들도 페디버스와 워드프레스의 연결을 보다 더 쉽게 이해하고 활용할 수 있습니다. 앞으로도 최신 문서와 기능 번역을 계속 업데이트할 예정이니 많은 관심과 피드백 부탁드립니다.
@pfefferle @obenland

#Automattic #WordPress #Activitypub
#워드프레스 #액티비티펍 #페디버스 #fediverse
https://ko.wordpress.org/plugins/activitypub/

Recently there has been a lot of discourse about ActivityPub and AT Protocol which has been quite dividing and heated.

Yesterday at the Social Web CG meeting (the group that maintains the ActivityPub and related specifications), I proposed releasing a statement that counters the narrative that one of these protocols must win, when both protocols can co-exist and have a lot to learn from each other.

The statement has been co-signed by various members of both Social Web CG, SocialCG, and the AT Protocol community.

“We do not win by tearing each other down, which only emboldens and empowers those who do not want either protocol to succeed.”

“Arguing between us only emboldens those that seek to derail and destroy efforts to build an open social web.”

You can read the full statement here:
https://writings.thisismissem.social/statement-on-discourse-about-activitypub-and-at-protocol/

This was originally in the swicg/general repository, and you can learn about that here:
https://github.com/swicg/general/blob/master/statements/2025-09-05-activitypub-and-atproto-discourse.md

#activitypub #atprotocol #atproto #SocialWeb

그래도 한 5%정도 사이트의 꼬라지를 갖춰간다... 이번달 안에 (테스트로) 공개할 수 있겠지...?

@dansup not sure if you're aware, flags are usually not the best choice to represent languages 🙂

Optique 0.4.0 Released!

Big update for our type-safe combinatorial #CLI parser for #TypeScript:

• Labeled merge groups: organize options logically
• Rich docs: brief, description & footer support
• @optique/temporal: new package for date/time parsing
• showDefault: automatic default value display

The help text has never looked this good!

#JavaScript #opensource #Node.js #Deno #Bun

Loops now has i18n support, you can demo it with English/French on our demo instance:

https://getloops.social/

#loops #i18n

@silverpill Thanks!

@hongminhee FEP-3b86 defines many such relations:

https://codeberg.org/fediverse/fep/src/branch/main/fep/3b86/fep-3b86.md

We're excited to announce Optique 0.4.0, which brings significant improvements to help text organization, enhanced documentation capabilities, and introduces comprehensive Temporal API support.

Optique is a type-safe combinatorial CLI parser for TypeScript that makes building command-line interfaces intuitive and maintainable. This release focuses on making your CLI applications more user-friendly and maintainable.

Better help text organization

One of the most visible improvements in Optique 0.4.0 is the enhanced help text organization. You can now label and group your options more effectively, making complex CLIs much more approachable for users.

Labeled merge groups

The merge() combinator now accepts an optional label parameter, solving a common pain point where developers had to choose between clean code structure and organized help output:

// Before: unlabeled merged options appeared scattered
const config = merge(connectionOptions, performanceOptions);

// Now: group related options under a clear section
const config = merge(
  "Server Configuration",  // New label parameter
  connectionOptions,
  performanceOptions
);

This simple addition makes a huge difference in help text readability, especially for CLIs with many options spread across multiple reusable modules.

The resulting help output clearly organizes options under the Server Configuration section:

Demo app showcasing labeled merge groups
Usage: demo-merge.ts --host STRING --port INTEGER --timeout INTEGER --retries
       INTEGER

Server Configuration:
  --host STRING               Server hostname or IP address
  --port INTEGER              Port number for the connection
  --timeout INTEGER           Connection timeout in seconds
  --retries INTEGER           Number of retry attempts

The new group() combinator

For cases where merge() doesn't apply, the new group() combinator lets you wrap any parser with a documentation label:

// Group mutually exclusive options under a clear section
const outputFormat = group(
  "Output Format",
  or(
    map(flag("--json"), () => "json"),
    map(flag("--yaml"), () => "yaml"),
    map(flag("--xml"), () => "xml"),
  )
);

This is particularly useful for organizing mutually exclusive flags, multiple inputs, or any parser that doesn't natively support labeling. The resulting help text becomes much more scannable and user-friendly.

Here's how the grouped output format options appear in the help text:

Demo app showcasing group combinator
Usage: demo-group.ts --json
       demo-group.ts --yaml
       demo-group.ts --xml

Output Format:
  --json                      Output in JSON format
  --yaml                      Output in YAML format
  --xml                       Output in XML format

Rich documentation support

Optique 0.4.0 introduces comprehensive documentation fields that can be added directly through the run() function, eliminating the need to modify parser definitions for documentation purposes.

Brief descriptions, detailed explanations, and footers

Both @optique/core/facade and @optique/run now support brief, description, and footer options through the run() function:

import { run } from "@optique/run";
import { message } from "@optique/core/message";

const result = run(parser, {
  brief: message`A powerful data processing tool`,
  description: message`This tool provides comprehensive data processing capabilities with support for multiple formats and transformations. It can handle JSON, YAML, and CSV files with automatic format detection.`,
  footer: message`Examples:
  myapp process data.json --format yaml
  myapp validate config.toml --strict

For more information, visit https://example.com/docs`,
  help: "option"
});

These documentation fields appear in both help output and error messages (when configured), providing consistent context throughout your CLI's user experience.

The complete help output demonstrates the rich documentation features with brief description, detailed explanation, option descriptions, default values, and footer information:

A powerful data processing tool
Usage: demo-rich-docs.ts [--port INTEGER] [--format STRING] --verbose STRING

This tool provides comprehensive data processing capabilities with support for
multiple formats and transformations. It can handle JSON, YAML, and CSV files
with automatic format detection.

  --port INTEGER              Server port number [3000]
  --format STRING             Output format [json]
  --verbose STRING            Verbosity level

Examples:
  myapp process data.json --format yaml
  myapp validate config.toml --strict

For more information, visit https://example.com/docs

These documentation fields appear in both help output and error messages (when configured), providing consistent context throughout your CLI's user experience.

Display default values

A frequently requested feature is now available: showing default values directly in help text. Enable this with the new showDefault option when using withDefault():

const parser = object({
  port: withDefault(
    option("--port", integer(), { description: message`Server port number` }),
    3000,
  ),
  format: withDefault(
    option("--format", string(), { description: message`Output format` }),
    "json",
  ),
});

run(parser, { showDefault: true });

// Or with custom formatting:
run(parser, {
  showDefault: {
    prefix: " (default: ",
    suffix: ")"
  }  // Shows: --port (default: 3000)
});

Default values are automatically dimmed when colors are enabled, making them visually distinct while remaining readable.

The help output shows default values clearly marked next to each option:

Usage: demo-defaults.ts [--port INTEGER] [--format STRING]

  --port INTEGER              Server port number [3000]
  --format STRING             Output format [json]

Temporal API support

Optique 0.4.0 introduces a new package, @optique/temporal, providing comprehensive support for the modern Temporal API. This brings type-safe parsing for dates, times, durations, and time zones:

import { instant, duration, zonedDateTime } from "@optique/temporal";
import { option } from "@optique/core/parser";

const parser = object({
  // Parse ISO 8601 timestamps
  timestamp: option("--at", instant()),

  // Parse durations like "PT30M" or "P1DT2H"
  timeout: option("--timeout", duration()),

  // Parse zoned datetime with timezone info
  meeting: option("--meeting", zonedDateTime()),
});

The temporal parsers return native Temporal objects with full functionality:

const result = parse(timestampArg, ["2023-12-25T10:30:00Z"]);
if (result.success) {
  const instant = result.value;
  console.log(`UTC: ${instant.toString()}`);
  console.log(`Seoul: ${instant.toZonedDateTimeISO("Asia/Seoul")}`);
}

Install the new package with:

npm add @optique/temporal

Improved type inference

The merge() combinator now supports up to 10 parsers (previously 5), and the tuple() parser has improved type inference using TypeScript's const type parameter. These enhancements enable more complex CLI structures while maintaining perfect type safety.

Breaking changes

While we've maintained backward compatibility for most APIs, there are a few changes to be aware of:

• The Parser.getDocFragments() method now uses DocState<TState> instead of direct state values (only affects custom parser implementations)
• The merge() combinator now enforces stricter type constraints at compile time, rejecting non-object-producing parsers

Learn more

For a complete list of changes, bug fixes, and improvements, see the full changelog.

Check out the updated documentation:

• Structured messages guide for the new documentation features
• Construct combinators reference for merge() and group() usage
• Value parsers guide for temporal parsing
• CLI patterns cookbook for practical examples

Installation

Upgrade to Optique 0.4.0:

npm update @optique/core @optique/run
# or
deno add jsr:@optique/core@^0.4.0 jsr:@optique/run@^0.4.0

Add temporal support (optional):

npm add @optique/temporal
# or
deno add jsr:@optique/temporal

We hope these improvements make building CLI applications with Optique even more enjoyable. As always, we welcome your feedback and contributions on GitHub.

Optique 0.4.0 Released!

Big update for our type-safe combinatorial #CLI parser for #TypeScript:

• Labeled merge groups: organize options logically
• Rich docs: brief, description & footer support
• @optique/temporal: new package for date/time parsing
• showDefault: automatic default value display

The help text has never looked this good!

#JavaScript #opensource #Node.js #Deno #Bun